Add public API (#593)

Add public API

Co-authored-by: Seth Silesky <silesky@users.noreply.github.com>

Author: silesky

.changeset/friendly-birds-happen.md

@@ -1,5 +1,4 @@
 ---
-'@segment/analytics-plugin-validation': major
 '@segment/analytics-core': minor
 ---
 

.changeset/proud-pens-raise.md

@@ -0,0 +1,6 @@
+---
+'@segment/analytics-core': patch
+'@segment/analytics-node': patch
+---
+
+Revise NodeJS public API. Fix core so Node SDK waits for plugins to be registered before dispatching any events.

internal/config/src/jest/config.js

@@ -1,17 +1,23 @@
 const { getJestModuleMap } = require('./get-module-map')
+const path = require('path')
 
 /**
  * Create Config
  * @param {import('jest').Config} Overrides.
  * @param {object} getJestModuleMap options.
  * @returns {import('jest').Config}
  */
-const createJestTSConfig = (
-  { modulePathIgnorePatterns, testMatch, ...overridesToMerge } = {},
-  { packageRoot, skipPackageMap } = {}
-) => {
+const createJestTSConfig = ({
+  modulePathIgnorePatterns,
+  testMatch,
+  ...overridesToMerge
+} = {}) => {
+  const moduleMap = getJestModuleMap()
   return {
-    moduleNameMapper: getJestModuleMap(packageRoot, skipPackageMap),
+    ...(global.JEST_ROOT_CONFIG
+      ? {}
+      : { displayName: path.basename(process.cwd()) }),
+    moduleNameMapper: moduleMap,
     preset: 'ts-jest',
     modulePathIgnorePatterns: [
       '<rootDir>/dist/',

internal/config/src/jest/get-module-map.js

@@ -4,26 +4,37 @@ const getPackages = require('get-monorepo-packages')
 const doNotMapPackages = process.env.JEST_SKIP_PACKAGE_MAP === 'true'
 
 /**
- * Allows ts-jest to dynamically resolve packages so "build"
+ * Create module mapping that resolve packages for ts-jest so typescript compilation happens in-memory
+ *
  */
-const getJestModuleMap = (
-  packageRoot = '../../',
-  skipPackageMap = doNotMapPackages
-) => {
+const getJestModuleMap = ({ skipPackageMap = doNotMapPackages } = {}) => {
   // get listing of packages in the mono repo
-  const createLocation = (name) => {
-    return `<rootDir>/./${name}/src/$1`
+
+  /**
+   * @param location - e.g. "packages/core"
+   */
+
+  const createPackageMappedPath = (location) => {
+    // if packageRoot is the global jest file (using projects), our mappers suddenly need
+    // to be relative to each project -- I have no idea why, seems unintuitive.
+    // If not root config, equiv to running "yarn test" in an individual package repo (rootDir will be the root package.json)
+    const moduleBasePath = global.JEST_ROOT_CONFIG
+      ? '<rootDir>/../..'
+      : '<rootDir>'
+    return `${moduleBasePath}/${location}/src/$1`
   }
+  // for the sake of getPackages working correctly during a project-wide test run, the working directory must be hardcoded to the root
+  const packageRoot = global.JEST_ROOT_CONFIG ? '.' : '../../'
   const moduleNameMapper = getPackages(packageRoot).reduce(
     (acc, el) => ({
       ...acc,
-      [`${el.package.name}(.*)$`]: createLocation(el.location),
+      [`${el.package.name}(.*)$`]: createPackageMappedPath(el.location),
     }),
     {}
   )
 
   return {
-    '@/(.+)': '<rootdir>/../../src/$1',
+    '@/(.+)': '<rootDir>/src/$1',
     ...(skipPackageMap ? {} : moduleNameMapper),
   }
 }

jest.config.js

@@ -0,0 +1,16 @@
+const { createJestTSConfig } = require('@internal/config')
+
+/**
+ * This config detects our monorepo, and allows
+ * you to run every single package test in a single jest instance using 'yarn jest'.
+ * Thus, `yarn jest --watch` works as expected (unlike say, when using turborepo)
+ */
+module.exports = () => {
+  // we actually need to set a global variable to preserve the correct path mapping when running project-wide jest.
+  global.JEST_ROOT_CONFIG = true
+
+  const config = createJestTSConfig({
+    projects: ['<rootDir>/packages/*'],
+  })
+  return config
+}

package.json

@@ -11,7 +11,7 @@
     "node": "^14.15.0"
   },
   "scripts": {
-    "test": "FORCE_COLOR=1 turbo run test --filter='./packages/*'",
+    "test": "jest",
     "test:scripts": "jest --config scripts/jest.config.js",
     "lint": "yarn constraints && turbo run lint",
     "build": "turbo run build --filter='./packages/*'",
@@ -37,6 +37,7 @@
     "@changesets/cli": "^2.23.2",
     "@npmcli/promise-spawn": "^3.0.0",
     "@types/jest": "^28.1.1",
+    "@types/lodash": "^4",
     "@typescript-eslint/eslint-plugin": "^5.21.0",
     "@typescript-eslint/parser": "^5.21.0",
     "concurrently": "^7.2.1",
@@ -47,6 +48,7 @@
     "husky": "^8.0.0",
     "jest": "^28.1.0",
     "lint-staged": "^13.0.0",
+    "lodash": "^4.17.21",
     "node-gyp": "^9.0.0",
     "prettier": "^2.6.2",
     "ts-jest": "^28.0.4",

packages/browser/package.json

@@ -69,7 +69,6 @@
     "@types/jquery": "^3.5.4",
     "@types/js-cookie": "3.0.1",
     "@types/jsdom": "^16.2.14",
-    "@types/lodash": "^4.14.161",
     "@types/mime": "^2.0.3",
     "@types/node": "^12.12.14",
     "@types/node-fetch": "^2.5.7",

packages/core/src/analytics/dispatch-emit.ts

@@ -0,0 +1,20 @@
+import { dispatch } from './dispatch'
+import { CoreContext } from '../context'
+
+/* Dispatch function, but swallow promise rejections and use event emitter instead */
+export const dispatchAndEmit = async (
+  ...[event, queue, emitter, options]: Parameters<typeof dispatch>
+) => {
+  try {
+    const ctx = await dispatch(event, queue, emitter, options)
+    if (ctx.failedDelivery()) {
+      throw ctx
+    } else {
+      emitter.emit(event.type, ctx)
+      return ctx
+    }
+  } catch (err) {
+    emitter.emit('error', err as CoreContext)
+    return err
+  }
+}

packages/core/src/analytics/index.ts

@@ -1,13 +1,11 @@
-import { CoreContext } from '../context'
-
 export interface CoreAnalytics {
-  track(...args: unknown[]): Promise<CoreContext>
-  page(...args: unknown[]): Promise<CoreContext>
-  identify(...args: unknown[]): Promise<CoreContext>
-  group(...args: unknown[]): Promise<CoreContext>
-  alias(...args: unknown[]): Promise<CoreContext>
-  screen(...args: unknown[]): Promise<CoreContext>
-  register(...plugins: unknown[]): Promise<CoreContext>
-  deregister(...plugins: unknown[]): Promise<CoreContext>
+  track(...args: unknown[]): unknown
+  page(...args: unknown[]): unknown
+  identify(...args: unknown[]): unknown
+  group(...args: unknown[]): unknown
+  alias(...args: unknown[]): unknown
+  screen(...args: unknown[]): unknown
+  register(...plugins: unknown[]): Promise<unknown>
+  deregister(...plugins: unknown[]): Promise<unknown>
   readonly VERSION: string
 }

packages/core/src/arguments-resolver/page.ts

@@ -1,4 +1,4 @@
-import { isFunction, isPlainObject, isString } from '../validation'
+import { isFunction, isPlainObject, isString } from '../validation/helpers'
 import { JSONObject, EventProperties, CoreOptions } from '../events'
 import { Callback } from '../events/interfaces'