Delay initialization (lazy loading) (#637)

Author: silesky

.changeset/friendly-mails-heal.md

@@ -0,0 +1,5 @@
+---
+'@segment/analytics-next': minor
+---
+
+Add ability to delay initialization

README.md

@@ -53,6 +53,29 @@ document.body?.addEventListener('click', () => {
 })
 ```
 
+## Lazy / Delayed Loading
+You can load a buffered version of analytics that requires `.load` to be explicitly called before initiating any network activity. This can be useful if you want to wait for a user to consent before fetching any tracking destinations or sending buffered events to segment.
+
+- ⚠️ ️`.load` should only be called _once_.
+
+```ts
+export const analytics = new AnalyticsBrowser()
+
+analytics.identify("hello world")
+
+if (userConsentsToBeingTracked) {
+    analytics.load({ writeKey: '<YOUR_WRITE_KEY>' }) // destinations loaded, enqueued events are flushed
+}
+```
+This strategy also comes in handy if you have some settings that are fetched asynchronously.
+```ts
+const analytics = new AnalyticsBrowser()
+fetchWriteKey().then(writeKey => analytics.load({ writeKey }))
+
+analytics.identify("hello world")
+```
+
+## Usage in Common Frameworks
 ### using `React` (Simple)
 
 ```tsx

packages/browser/README.md

@@ -53,7 +53,30 @@ document.body?.addEventListener('click', () => {
 })
 ```
 
-### using `React` (Simple / client-side only)
+## Lazy / Delayed Loading
+You can load a buffered version of analytics that requires `.load` to be explicitly called before initiating any network activity. This can be useful if you want to wait for a user to consent before fetching any tracking destinations or sending buffered events to segment.
+
+- ⚠️ ️`.load` should only be called _once_.
+
+```ts
+export const analytics = new AnalyticsBrowser()
+
+analytics.identify("hello world")
+
+if (userConsentsToBeingTracked) {
+    analytics.load({ writeKey: '<YOUR_WRITE_KEY>' }) // destinations loaded, enqueued events are flushed
+}
+```
+This strategy also comes in handy if you have some settings that are fetched asynchronously.
+```ts
+const analytics = new AnalyticsBrowser()
+fetchWriteKey().then(writeKey => analytics.load({ writeKey }))
+
+analytics.identify("hello world")
+```
+
+## Usage in Common Frameworks
+### using `React` (Simple)
 
 ```tsx
 import { AnalyticsBrowser } from '@segment/analytics-next'
@@ -71,6 +94,8 @@ const App = () => (
 ### using `React` (Advanced w/ React Context)
 
 ```tsx
+import { AnalyticsBrowser } from '@segment/analytics-next'
+
 const AnalyticsContext = React.createContext<AnalyticsBrowser>(undefined!);
 
 type Props = {
@@ -102,7 +127,7 @@ export const useAnalytics = () => {
 const TrackButton = () => {
   const analytics = useAnalytics()
   return (
-    <button onClick={() => analytics.track('hello world').then(console.log)}>
+    <button onClick={() => analytics.track('hello world')}>
       Track!
     </button>
   )
@@ -126,7 +151,7 @@ More React Examples:
 1. create composable file `segment.ts` with factory ref analytics:
 
 ```ts
-import { Analytics, AnalyticsBrowser } from '@segment/analytics-next'
+import { AnalyticsBrowser } from '@segment/analytics-next'
 
 export const analytics = AnalyticsBrowser.load({
   writeKey: '<YOUR_WRITE_KEY>',
@@ -200,7 +225,10 @@ First, clone the repo and then startup our local dev environment:
 ```sh
 $ git clone git@github.com:segmentio/analytics-next.git
 $ cd analytics-next
-$ yarn dev
+$ nvm use  # installs correct version of node defined in .nvmrc.
+$ yarn && yarn build
+$ yarn test
+$ yarn dev  # optional: runs analytics-next playground.
 ```
 
 > If you get "Cannot find module '@segment/analytics-next' or its corresponding type declarations.ts(2307)" (in VSCode), you may have to "cmd+shift+p -> "TypeScript: Restart TS server"

packages/browser/package.json

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

packages/browser/src/browser/__tests__/analytics-lazy-init.integration.test.ts

@@ -0,0 +1,49 @@
+import { sleep } from '@segment/analytics-core'
+import unfetch from 'unfetch'
+import { AnalyticsBrowser } from '..'
+import { Analytics } from '../../core/analytics'
+import { createSuccess } from '../../test-helpers/factories'
+
+jest.mock('unfetch')
+
+const mockFetchSettingsSuccessResponse = () => {
+  return jest
+    .mocked(unfetch)
+    .mockImplementation(() => createSuccess({ integrations: {} }))
+}
+
+describe('Lazy initialization', () => {
+  let trackSpy: jest.SpiedFunction<Analytics['track']>
+  let fetched: jest.MockedFn<typeof unfetch>
+  beforeEach(() => {
+    fetched = mockFetchSettingsSuccessResponse()
+    trackSpy = jest.spyOn(Analytics.prototype, 'track')
+  })
+
+  it('Should be able to delay initialization ', async () => {
+    const analytics = new AnalyticsBrowser()
+    const track = analytics.track('foo')
+    await sleep(100)
+    expect(trackSpy).not.toBeCalled()
+    analytics.load({ writeKey: 'abc' })
+    await track
+    expect(trackSpy).toBeCalledWith('foo')
+  })
+
+  it('.load method return an analytics instance', async () => {
+    const analytics = new AnalyticsBrowser().load({ writeKey: 'foo' })
+    expect(analytics instanceof AnalyticsBrowser).toBeTruthy()
+  })
+
+  it('should ignore subsequent .load calls', async () => {
+    const analytics = new AnalyticsBrowser()
+    await analytics.load({ writeKey: 'my-write-key' })
+    await analytics.load({ writeKey: 'def' })
+    expect(fetched).toBeCalledTimes(1)
+    expect(fetched).toBeCalledWith(
+      expect.stringContaining(
+        'https://cdn.segment.com/v1/projects/my-write-key/settings'
+      )
+    )
+  })
+})

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

@@ -110,4 +110,16 @@ export default {
     }
     void AnalyticsBrowser.load({ writeKey: 'foo' }).track('foo', {} as User)
   },
+  'Lazy instantiation should be supported': () => {
+    const analytics = new AnalyticsBrowser()
+    assertNotAny(analytics)
+    assertIs<AnalyticsBrowser>(analytics)
+    analytics.load({ writeKey: 'foo' })
+    void analytics.track('foo')
+  },
+  '.load should return this': () => {
+    const analytics = new AnalyticsBrowser().load({ writeKey: 'foo' })
+    assertNotAny(analytics)
+    assertIs<AnalyticsBrowser>(analytics)
+  },
 }

packages/browser/src/browser/index.ts

@@ -8,6 +8,7 @@ import { Plan } from '../core/events'
 import { Plugin } from '../core/plugin'
 import { MetricsOptions } from '../core/stats/remote-metrics'
 import { mergedOptions } from '../lib/merged-options'
+import { createDeferred } from '../lib/create-deferred'
 import { pageEnrichment } from '../plugins/page-enrichment'
 import { remoteLoader, RemotePlugin } from '../plugins/remote-loader'
 import type { RoutingRule } from '../plugins/routing-middleware'
@@ -18,7 +19,6 @@ import {
   PreInitMethodCallBuffer,
   flushAnalyticsCallsInNewTask,
   flushAddSourceMiddleware,
-  AnalyticsLoader,
   flushSetAnonymousID,
   flushOn,
 } from '../core/buffer'
@@ -309,17 +309,63 @@ async function loadAnalytics(
 }
 
 /**
- * The public browser interface for this package.
- * Use AnalyticsBrowser.load to create an instance.
+ * The public browser interface for Segment Analytics
+ *
+ * @example
+ * ```ts
+ *  export const analytics = new AnalyticsBrowser()
+ *  analytics.load({ writeKey: 'foo' })
+ * ```
+ * @link https://github.com/segmentio/analytics-next/#readme
  */
 export class AnalyticsBrowser extends AnalyticsBuffered {
-  private constructor(loader: AnalyticsLoader) {
-    super(loader)
+  private _resolveLoadStart: (
+    settings: AnalyticsBrowserSettings,
+    options: InitOptions
+  ) => void
+
+  constructor() {
+    const { promise: loadStart, resolve: resolveLoadStart } =
+      createDeferred<Parameters<AnalyticsBrowser['load']>>()
+
+    super((buffer) =>
+      loadStart.then(([settings, options]) =>
+        loadAnalytics(settings, options, buffer)
+      )
+    )
+
+    this._resolveLoadStart = (settings, options) =>
+      resolveLoadStart([settings, options])
+  }
+
+  /**
+   * Fully initialize an analytics instance, including:
+   *
+   * * Fetching settings from the segment CDN (by default).
+   * * Fetching all remote destinations configured by the user (if applicable).
+   * * Flushing buffered analytics events.
+   * * Loading all middleware.
+   *
+   * Note:️  This method should only be called *once* in your application.
+   *
+   * @example
+   * ```ts
+   * export const analytics = new AnalyticsBrowser()
+   * analytics.load({ writeKey: 'foo' })
+   * ```
+   */
+  load(
+    settings: AnalyticsBrowserSettings,
+    options: InitOptions = {}
+  ): AnalyticsBrowser {
+    this._resolveLoadStart(settings, options)
+    return this
   }
 
   /**
    * Instantiates an object exposing Analytics methods.
    *
+   * @example
    * ```ts
    * const ajs = AnalyticsBrowser.load({ writeKey: '<YOUR_WRITE_KEY>' })
    *
@@ -331,9 +377,7 @@ export class AnalyticsBrowser extends AnalyticsBuffered {
     settings: AnalyticsBrowserSettings,
     options: InitOptions = {}
   ): AnalyticsBrowser {
-    return new this((preInitBuffer) =>
-      loadAnalytics(settings, options, preInitBuffer)
-    )
+    return new AnalyticsBrowser().load(settings, options)
   }
 
   static standalone(

packages/browser/src/lib/create-deferred.ts

@@ -0,0 +1,16 @@
+/**
+ * Return a promise that can be externally resolved
+ */
+export const createDeferred = <T>() => {
+  let resolve!: (value: T | PromiseLike<T>) => void
+  let reject!: (reason: any) => void
+  const promise = new Promise<T>((_resolve, _reject) => {
+    resolve = _resolve
+    reject = _reject
+  })
+  return {
+    resolve,
+    reject,
+    promise,
+  }
+}