Make trait and extra context fields nullable

Author: silesky

.buildkite/pipeline.yml

@@ -99,6 +99,7 @@ steps:
       - echo "+++ Run tests"
       - yarn run -T core lint
       - yarn run -T core test
+      - yarn turbo run --filter=core-integration-tests lint
     plugins:
       - ssh://[email protected]/segmentio/cache-buildkite-plugin#v2.0.0:
           key: "v1.1-cache-dev-{{ checksum 'yarn.lock' }}"

.changeset/hip-parents-smell.md

@@ -0,0 +1,5 @@
+---
+'@segment/analytics-core': patch
+---
+
+Make trait and extra context fields nullable.

package.json

@@ -23,11 +23,11 @@
     "release": "yarn clean && yarn build --force && changeset publish && git push origin HEAD:master --follow-tags --no-verify",
     "version-run-all": "yarn workspaces foreach -vpt --no-private run version",
     "core": "yarn workspace @segment/analytics-core",
-    "core+deps": "turbo run --filter=@segment/analytics-core...",
+    "core+deps": "turbo run --filter=@segment/analytics-core",
     "browser": "yarn workspace @segment/analytics-next",
-    "browser+deps": "turbo run --filter=@segment/analytics-next...",
+    "browser+deps": "turbo run --filter=@segment/analytics-next",
     "node": "yarn workspace @segment/analytics-node",
-    "node+deps": "turbo run --filter=@segment/analytics-node...",
+    "node+deps": "turbo run --filter=@segment/analytics-node",
     "clean": "bash scripts/clean.sh"
   },
   "packageManager": "[email protected]",

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

@@ -119,12 +119,34 @@ export default {
     assertNotAny(analytics)
     assertIs<AnalyticsBrowser>(analytics)
   },
-  'Should error if there is a type conflict in Traits': () => {
-    const analytics = new AnalyticsBrowser().load({ writeKey: 'foo' })
-    assertNotAny(analytics)
-    assertIs<AnalyticsBrowser>(analytics)
 
-    // @ts-expect-error - id should be a string
-    void analytics.identify('foo', { id: 123 })
+  'Should accept traits': () => {
+    const analytics = {} as AnalyticsBrowser
+
+    class Foo {
+      name = 'hello'
+      toJSON() {
+        return this.name
+      }
+    }
+    void analytics.identify('foo', new Foo())
+    void analytics.identify('foo', { address: null })
+    // @ts-expect-error - Type 'string' has no properties in common with type
+    void analytics.identify('foo', { address: 'hello' })
+    // @ts-expect-error - Type 'never[]' is not assignable to type
+    void analytics.identify('foo', { id: [] })
+  },
+
+  'Should accept optional ExtraContext': () => {
+    const analytics = {} as AnalyticsBrowser
+    void analytics.track('foo', undefined, { context: {} })
+    void analytics.track('foo', undefined, { context: { active: null } })
+    void analytics.track('foo', undefined, { context: { active: true } })
+    void analytics.track('foo', undefined, {
+      context: {
+        // @ts-expect-error Type 'string' is not assignable to type 'boolean | null | undefined'.ts(2322)
+        active: 'hello',
+      },
+    })
   },
 }

packages/core-integration-tests/src/typedef-tests.ts

@@ -0,0 +1,36 @@
+import { CoreAnalyticsTraits, CoreExtraContext } from '@segment/analytics-core'
+
+class TestClass {
+  name = 'hello'
+  toJSON() {
+    return this.name
+  }
+}
+
+export default {
+  'CoreAnalyticsTraits test': () => {
+    let traits: CoreAnalyticsTraits = {}
+
+    // should accept a class
+    traits = new TestClass()
+    // should be nullable
+    traits = { address: null }
+    // should accept aribtrary properties
+    traits = { address: {}, foo: 123 }
+    // should fail with type conflicts
+    // @ts-expect-error
+    traits = { address: 'hello' }
+  },
+
+  'CoreExtraContext test': () => {
+    // should accept a class
+    let ec: CoreExtraContext = {}
+    ec = new TestClass()
+    // should be nullable
+    ec = { page: null }
+    ec = { page: { path: null } }
+    // should error if type conflict
+    // @ts-expect-error
+    ec = { page: { path: {} } }
+  },
+}

packages/core/src/events/interfaces.ts

@@ -1,5 +1,6 @@
 import { CoreContext } from '../context'
 import { ID } from '../user'
+import { DeepNullable } from '../utils/ts-helpers'
 
 export type Callback<Ctx extends CoreContext = CoreContext> = (
   ctx: Ctx
@@ -46,47 +47,47 @@ export interface CoreExtraContext {
   /**
    * This is usually used to flag an .identify() call to just update the trait, rather than "last seen".
    */
-  active?: boolean
+  active?: boolean | null
 
   /**
    * Current user's IP address.
    */
-  ip?: string
+  ip?: string | null
 
   /**
    * Locale string for the current user, for example en-US.
    * @example en-US
    */
-  locale?: string
+  locale?: string | null
   /**
    * Dictionary of information about the user’s current location.
    */
   location?: {
     /**
      * @example San Francisco
      */
-    city?: string
+    city?: string | null
     /**
      * @example United States
      */
-    country?: string
+    country?: string | null
     /**
      * @example 40.2964197
      */
-    latitude?: string
+    latitude?: string | null
     /**
      * @example -76.9411617
      */
-    longitude?: string
+    longitude?: string | null
     /**
      * @example CA
      */
-    region?: string
+    region?: string | null
     /**
      * @example 100
      */
-    speed?: number
-  }
+    speed?: number | null
+  } | null
 
   /**
    * Dictionary of information about the current web page.
@@ -95,29 +96,29 @@ export interface CoreExtraContext {
     /**
      * @example /academy/
      */
-    path?: string
+    path?: string | null
     /**
      * @example https://www.foo.com/
      */
-    referrer?: string
+    referrer?: string | null
     /**
      * @example projectId=123
      */
-    search?: string
+    search?: string | null
     /**
      * @example Analytics Academy
      */
-    title?: string
+    title?: string | null
     /**
      * @example https://segment.com/academy/
      */
-    url?: string
-  }
+    url?: string | null
+  } | null
 
   /**
    * User agent of the device making the request.
    */
-  userAgent?: string
+  userAgent?: string | null
 
   /**
    * Information about the current library.
@@ -135,14 +136,14 @@ export interface CoreExtraContext {
      * @example  "1.43.1"
      */
     version: string
-  }
+  } | null
 
   /**
    * This is useful in cases where you need to track an event,
    * but also associate information from a previous identify call.
    * You should fill this object the same way you would fill traits in an identify call.
    */
-  traits?: CoreAnalyticsTraits
+  traits?: CoreAnalyticsTraits | null
 
   /**
    * Dictionary of information about the campaign that resulted in the API call, containing name, source, medium, term, content, and any other custom UTM parameter.
@@ -153,26 +154,26 @@ export interface CoreExtraContext {
     source: string
     medium: string
     content: string
-  }
+  } | null
 
   /**
    * Dictionary of information about the way the user was referred to the website or app.
    */
   referrer?: {
-    type?: string
-    name?: string
-    url?: string
-    link?: string
+    type?: string | null
+    name?: string | null
+    url?: string | null
+    link?: string | null
 
-    id?: string // undocumented
-    btid?: string // undocumented?
-    urid?: string // undocumented?
-  }
+    id?: string | null // undocumented
+    btid?: string | null // undocumented?
+    urid?: string | null // undocumented?
+  } | null
 
   amp?: {
     // undocumented?
     id: string
-  }
+  } | null
 
   [key: string]: any
 }
@@ -255,11 +256,11 @@ export interface PlanEvent {
  * @link https://segment.com/docs/connections/spec/identify/#traits
  * @link https://segment.com/docs/connections/spec/group/#traits
  */
-export interface CoreAnalyticsTraits {
+export type CoreAnalyticsTraits = DeepNullable<{
   /**
    * Unique ID in your database for a user/group.
    */
-  id?: string
+  id?: string | number
 
   /**
    * Industry a user works in, or a group is part of.
@@ -372,4 +373,4 @@ export interface CoreAnalyticsTraits {
   gender?: string
 
   [customTrait: string]: any
-}
+}>

packages/core/src/utils/ts-helpers.ts

@@ -4,3 +4,10 @@
 export type RemoveIndexSignature<T> = {
   [K in keyof T as {} extends Record<K, 1> ? never : K]: T[K]
 }
+
+/**
+ * Recursively make all object properties nullable
+ */
+export type DeepNullable<T> = {
+  [K in keyof T]: T[K] extends object ? DeepNullable<T[K]> | null : T[K] | null
+}