Refactor / break up node types (#712)

Author: silesky

packages/node/src/__tests__/graceful-shutdown-integration.test.ts

@@ -4,9 +4,10 @@ import { performance as perf } from 'perf_hooks'
 const fetcher = jest.fn()
 jest.mock('../lib/fetch', () => ({ fetch: fetcher }))
 
-import { Analytics, SegmentEvent } from '../app/analytics-node'
+import { Analytics } from '../app/analytics-node'
 import { sleep } from './test-helpers/sleep'
 import { CoreContext, CorePlugin } from '@segment/analytics-core'
+import { SegmentEvent } from '../app/types'
 
 const testPlugin: CorePlugin = {
   type: 'after',

packages/node/src/__tests__/typedef-tests.ts

@@ -1,4 +1,4 @@
-import { Analytics } from '../'
+import { Analytics, Context, Plugin, Traits } from '../'
 
 /**
  * These are general typescript definition tests;
@@ -44,4 +44,15 @@ export default {
       previousId: 'foo',
     })
   },
+
+  'context should be exported': () => {
+    console.log(Context)
+  },
+  'plugin should be exported': () => {
+    interface MyPlugin extends Plugin {}
+    console.log({} as MyPlugin)
+  },
+  'traits should be exported': () => {
+    console.log({} as Traits)
+  },
 }

packages/node/src/app/analytics-node.ts

@@ -1,74 +1,33 @@
 import {
-  EventProperties,
   CoreAnalytics,
-  CoreContext,
-  CorePlugin,
   EventFactory,
   EventQueue,
   CoreSegmentEvent,
   bindAll,
-  PriorityQueue,
   pTimeout,
-  Integrations,
-  CoreExtraContext,
-  CoreAnalyticsTraits,
+  CoreContext,
 } from '@segment/analytics-core'
 import { AnalyticsSettings, validateSettings } from './settings'
 import { version } from '../../package.json'
 import { createConfiguredNodePlugin } from '../plugins/segmentio'
-import { createNodeEventFactory } from '../lib/create-node-event-factory'
+import { NodeEventFactory } from './event-factory'
 import { Callback, dispatchAndEmit } from './dispatch-emit'
 import { NodeEmitter } from './emitter'
+import {
+  AliasParams,
+  GroupParams,
+  IdentifyParams,
+  PageParams,
+  TrackParams,
+  Plugin,
+  SegmentEvent,
+} from './types'
+import { NodeEventQueue } from './event-queue'
 
 // create a derived class since we may want to add node specific things to Context later
+// While this is not a type, it is a definition
 export class Context extends CoreContext {}
 
-export interface Plugin extends CorePlugin {}
-type Timestamp = string | Date
-
-/**
- * An ID associated with the user. Note: at least one of userId or anonymousId must be included.
- **/
-type IdentityOptions =
-  | { userId: string; anonymousId?: string }
-  | { userId?: string; anonymousId: string }
-
-/**
- * A dictionary of extra context to attach to the call.
- * Note: context differs from traits because it is not attributes of the user itself.
- */
-export interface ExtraContext extends CoreExtraContext {}
-
-/**
- * Traits are pieces of information you know about a user that are included in an identify call. These could be demographics like age or gender, account-specific like plan, or even things like whether a user has seen a particular A/B test variation. Up to you!
- * Segment has reserved some traits that have semantic meanings for users, and we handle them in special ways. For example, Segment always expects email to be a string of the user’s email address.
- *
- * We’ll send this on to destinations like Mailchimp that require an email address for their tracking.
- *
- * You should only use reserved traits for their intended meaning.
- */
-export interface Traits extends CoreAnalyticsTraits {}
-
-class NodePriorityQueue extends PriorityQueue<Context> {
-  constructor() {
-    super(1, [])
-  }
-  // do not use an internal "seen" map
-  getAttempts(ctx: Context): number {
-    return ctx.attempts ?? 0
-  }
-  updateAttempts(ctx: Context): number {
-    ctx.attempts = this.getAttempts(ctx) + 1
-    return this.getAttempts(ctx)
-  }
-}
-
-type SegmentEventType = 'track' | 'page' | 'identify' | 'alias' | 'screen'
-
-export interface SegmentEvent extends CoreSegmentEvent {
-  type: SegmentEventType
-}
-
 export class Analytics extends NodeEmitter implements CoreAnalytics {
   private readonly _eventFactory: EventFactory
   private _isClosed = false
@@ -86,8 +45,8 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
     super()
     validateSettings(settings)
 
-    this._eventFactory = createNodeEventFactory()
-    this._queue = new EventQueue(new NodePriorityQueue())
+    this._eventFactory = new NodeEventFactory()
+    this._queue = new NodeEventQueue()
 
     const flushInterval = settings.flushInterval ?? 10000
 
@@ -161,21 +120,7 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
    * @link https://segment.com/docs/connections/sources/catalog/libraries/server/node/#alias
    */
   alias(
-    {
-      userId,
-      previousId,
-      context,
-      timestamp,
-      integrations,
-    }: {
-      /* The new user id you want to associate with the user. */
-      userId: string
-      /* The previous id that the user was recognized by (this can be either a userId or an anonymousId). */
-      previousId: string
-      context?: ExtraContext
-      timestamp?: Timestamp
-      integrations?: Integrations
-    },
+    { userId, previousId, context, timestamp, integrations }: AliasParams,
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.alias(userId, previousId, {
@@ -199,13 +144,7 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
       traits = {},
       context,
       integrations,
-    }: IdentityOptions & {
-      groupId: string
-      traits?: Traits
-      context?: ExtraContext
-      timestamp?: Timestamp
-      integrations?: Integrations
-    },
+    }: GroupParams,
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.group(groupId, traits, {
@@ -224,17 +163,7 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
    * @link https://segment.com/docs/connections/sources/catalog/libraries/server/node/#identify
    */
   identify(
-    {
-      userId,
-      anonymousId,
-      traits = {},
-      context,
-      integrations,
-    }: IdentityOptions & {
-      traits?: Traits
-      context?: ExtraContext
-      integrations?: Integrations
-    },
+    { userId, anonymousId, traits = {}, context, integrations }: IdentifyParams,
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.identify(userId, traits, {
@@ -260,17 +189,7 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
       context,
       timestamp,
       integrations,
-    }: IdentityOptions & {
-      /*  The category of the page. Useful for cases like ecommerce where many pages might live under a single category. */
-      category?: string
-      /* The name of the page.*/
-      name?: string
-      /* A dictionary of properties of the page. */
-      properties?: EventProperties
-      timestamp?: Timestamp
-      context?: ExtraContext
-      integrations?: Integrations
-    },
+    }: PageParams,
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.page(
@@ -298,7 +217,7 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
       context,
       timestamp,
       integrations,
-    }: Parameters<Analytics['page']>[0],
+    }: PageParams,
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.screen(
@@ -324,13 +243,7 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
       context,
       timestamp,
       integrations,
-    }: IdentityOptions & {
-      event: string
-      properties?: EventProperties
-      context?: ExtraContext
-      timestamp?: Timestamp
-      integrations?: Integrations
-    },
+    }: TrackParams,
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.track(event, properties, {
@@ -348,7 +261,7 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
    * Registers one or more plugins to augment Analytics functionality.
    * @param plugins
    */
-  async register(...plugins: CorePlugin<any, any>[]): Promise<void> {
+  async register(...plugins: Plugin[]): Promise<void> {
     return this._queue.criticalTasks.run(async () => {
       const ctx = Context.system()
 

packages/node/src/app/emitter.ts

@@ -1,6 +1,7 @@
 import { CoreEmitterContract, Emitter } from '@segment/analytics-core'
-import type { SegmentEvent, Context } from './analytics-node'
+import { Context } from './analytics-node'
 import type { AnalyticsSettings } from './settings'
+import { SegmentEvent } from './types'
 
 /**
  * Map of emitter event names to method args.

packages/node/src/app/event-factory.ts

@@ -0,0 +1,8 @@
+import { EventFactory } from '@segment/analytics-core'
+import { createMessageId } from '../lib/get-message-id'
+
+export class NodeEventFactory extends EventFactory {
+  constructor() {
+    super({ createMessageId })
+  }
+}

packages/node/src/app/event-queue.ts

@@ -0,0 +1,22 @@
+import { EventQueue, PriorityQueue } from '@segment/analytics-core'
+import type { Context } from './analytics-node'
+
+class NodePriorityQueue extends PriorityQueue<Context> {
+  constructor() {
+    super(1, [])
+  }
+  // do not use an internal "seen" map
+  getAttempts(ctx: Context): number {
+    return ctx.attempts ?? 0
+  }
+  updateAttempts(ctx: Context): number {
+    ctx.attempts = this.getAttempts(ctx) + 1
+    return this.getAttempts(ctx)
+  }
+}
+
+export class NodeEventQueue extends EventQueue {
+  constructor() {
+    super(new NodePriorityQueue())
+  }
+}

packages/node/src/app/types/index.ts

@@ -0,0 +1,3 @@
+export * from './params'
+export * from './segment-event'
+export * from './plugin'

packages/node/src/app/types/params.ts

@@ -0,0 +1,74 @@
+import type {
+  CoreAnalyticsTraits,
+  CoreExtraContext,
+  EventProperties,
+  Integrations,
+  Timestamp,
+} from '@segment/analytics-core'
+
+/**
+ * Traits are pieces of information you know about a user that are included in an identify call. These could be demographics like age or gender, account-specific like plan, or even things like whether a user has seen a particular A/B test variation. Up to you!
+ * Segment has reserved some traits that have semantic meanings for users, and we handle them in special ways. For example, Segment always expects email to be a string of the user’s email address.
+ *
+ * We’ll send this on to destinations like Mailchimp that require an email address for their tracking.
+ *
+ * You should only use reserved traits for their intended meaning.
+ */
+export interface Traits extends CoreAnalyticsTraits {}
+
+/**
+ * A dictionary of extra context to attach to the call.
+ * Note: context differs from traits because it is not attributes of the user itself.
+ */
+export interface ExtraContext extends CoreExtraContext {}
+
+/**
+ * An ID associated with the user. Note: at least one of userId or anonymousId must be included.
+ **/
+type IdentityOptions =
+  | { userId: string; anonymousId?: string }
+  | { userId?: string; anonymousId: string }
+
+export type AliasParams = {
+  /* The new user id you want to associate with the user. */
+  userId: string
+  /* The previous id that the user was recognized by (this can be either a userId or an anonymousId). */
+  previousId: string
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+}
+
+export type GroupParams = IdentityOptions & {
+  groupId: string
+  traits?: Traits
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+}
+
+export type IdentifyParams = IdentityOptions & {
+  traits?: Traits
+  context?: ExtraContext
+  integrations?: Integrations
+}
+
+export type PageParams = IdentityOptions & {
+  /*  The category of the page. Useful for cases like ecommerce where many pages might live under a single category. */
+  category?: string
+  /* The name of the page.*/
+  name?: string
+  /* A dictionary of properties of the page. */
+  properties?: EventProperties
+  timestamp?: Timestamp
+  context?: ExtraContext
+  integrations?: Integrations
+}
+
+export type TrackParams = IdentityOptions & {
+  event: string
+  properties?: EventProperties
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+}

packages/node/src/app/types/plugin.ts

@@ -0,0 +1,3 @@
+import type { CorePlugin } from '@segment/analytics-core'
+
+export interface Plugin extends CorePlugin {}

packages/node/src/app/types/segment-event.ts

@@ -0,0 +1,7 @@
+import type { CoreSegmentEvent } from '@segment/analytics-core'
+
+type SegmentEventType = 'track' | 'page' | 'identify' | 'alias' | 'screen'
+
+export interface SegmentEvent extends CoreSegmentEvent {
+  type: SegmentEventType
+}