Analytics Utility Functions

1.1.1 · active · verified Sun Apr 19

analytics-utils is a lightweight utility library providing common data manipulation functions specifically designed to support the 'analytics' module ecosystem. Currently at version 1.1.1, this package does not follow a strict time-based release cadence but typically releases new versions in conjunction with updates or new features in the primary 'analytics' library. Its key differentiators include a focused API tailored for analytics payload processing, often leveraging immutable data patterns, and first-class TypeScript support. It is not intended as a general-purpose utility library like Lodash or Ramda, but rather as a specialized toolkit for tasks such as deep property access, data cleaning, and transformation within an analytics context.

Common errors

```
TypeError: (0 , analytics_utils__WEBPACK_IMPORTED_MODULE_0__.get) is not a function
```
cause Attempting to call a named export (`get`) on a module that was incorrectly imported as a default export, or a CommonJS module being treated as an ESM module without proper interop.

fix Ensure you are using named imports for individual utilities: `import { get } from 'analytics-utils';`
```
Property 'someUtil' does not exist on type 'typeof import("analytics-utils")'. Did you mean 'someOtherUtil'?
```
cause Attempting to import a utility function with an incorrect name or a function that no longer exists/was never part of the public API. TypeScript flags this at compile time.

fix Consult the `analytics-utils` documentation or source code to verify the exact name of the utility function you intend to use. Most utilities are named exports.

Warnings

gotcha `set` and similar data manipulation functions in `analytics-utils` are designed to be immutable, returning a new object with the changes rather than modifying the original object in place. Failing to assign the return value will result in no change to your data.
Fix: Always capture the return value of functions like `set`: `const newObject = set(originalObject, 'path', value);`
breaking Prior to v1.0.0, some utility functions might have been directly available on a default export or required different import paths. As of v1.0.0, the package primarily uses named exports for individual utilities.
Fix: Update your imports to use named exports: `import { utilityName } from 'analytics-utils';`. Review the specific utility function names as some might have been renamed for consistency.
gotcha The `get` utility function, if a path does not exist, will return `undefined`. While this is standard, ensure your code explicitly handles `undefined` return values to prevent runtime errors when accessing properties of non-existent nested objects.
Fix: Use nullish coalescing or optional chaining where appropriate: `const value = get(obj, 'path') ?? 'defaultValue';` or `const value = get(obj, 'path')?.someProp;`
deprecated Older versions of the `analytics` module might have bundled some of these utilities directly. Relying on such implicit re-exports is deprecated. Always import utilities directly from `analytics-utils` for forward compatibility and clarity.
Fix: Migrate any direct `analytics` module utility calls to explicit imports from `analytics-utils`: `import { utility } from 'analytics-utils';`

Install

npm install analytics-utils npm
yarn add analytics-utils yarn
pnpm add analytics-utils pnpm

Imports

get
wrong:
```
const get = require('analytics-utils').get
```
correct:
```
import { get } from 'analytics-utils'
```
While CommonJS `require` might work in Node.js, `analytics-utils` is primarily designed for modern JavaScript environments using ESM. For deep object access, `get` is a common utility.
set
wrong:
```
import set from 'analytics-utils'
```
correct:
```
import { set } from 'analytics-utils'
```
Most utilities are named exports. Attempting a default import for `set` will result in `undefined` or an error. This function is for setting deep properties immutably.
isPlainObject
wrong:
```
import { isObject } from 'analytics-utils'
```
correct:
```
import { isPlainObject } from 'analytics-utils'
```
The library likely offers specific type-checking utilities like `isPlainObject` rather than a generic `isObject` to differentiate from arrays, functions, etc. Always check exact utility names.

Quickstart

Demonstrates importing and using common `analytics-utils` functions like `get`, `set`, and `isPlainObject` for manipulating analytics event data, showcasing deep property access, immutable updates, and type checking.

import { get, set, isPlainObject } from 'analytics-utils';

interface AnalyticsEvent {
  eventName: string;
  payload: Record<string, any>;
  context?: Record<string, any>;
}

const originalEvent: AnalyticsEvent = {
  eventName: 'UserLoggedIn',
  payload: {
    userId: 'abc-123',
    email: 'user@example.com',
    preferences: {
      theme: 'dark',
      notifications: true
    }
  },
  context: {
    platform: 'web',
    device: 'desktop'
  }
};

// Get a deep property
const userTheme = get(originalEvent, 'payload.preferences.theme');
console.log('User Theme:', userTheme); // 'dark'

// Set a deep property (immutably returns a new object)
const updatedEvent = set(originalEvent, 'payload.preferences.notifications', false);
console.log('Original notifications:', get(originalEvent, 'payload.preferences.notifications')); // true
console.log('Updated notifications:', get(updatedEvent, 'payload.preferences.notifications'));   // false

// Check if a value is a plain object
const isPayloadObject = isPlainObject(originalEvent.payload);
console.log('Is payload a plain object?', isPayloadObject); // true

const isUserThemeObject = isPlainObject(userTheme);
console.log('Is userTheme a plain object?', isUserThemeObject); // false

view raw JSON →