{"id":14423,"library":"analytics-utils","title":"Analytics Utility Functions","description":"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.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/DavidWells/analytics","tags":["javascript","analytics","analytics-project","analytics-utilities","typescript"],"install":[{"cmd":"npm install analytics-utils","lang":"bash","label":"npm"},{"cmd":"yarn add analytics-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add analytics-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides type definitions for the 'dlv' package, which is likely used internally or re-exported for deep object value retrieval.","package":"@types/dlv","optional":true}],"imports":[{"note":"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.","wrong":"const get = require('analytics-utils').get","symbol":"get","correct":"import { get } from 'analytics-utils'"},{"note":"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.","wrong":"import set from 'analytics-utils'","symbol":"set","correct":"import { set } from 'analytics-utils'"},{"note":"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.","wrong":"import { isObject } from 'analytics-utils'","symbol":"isPlainObject","correct":"import { isPlainObject } from 'analytics-utils'"}],"quickstart":{"code":"import { get, set, isPlainObject } from 'analytics-utils';\n\ninterface AnalyticsEvent {\n  eventName: string;\n  payload: Record<string, any>;\n  context?: Record<string, any>;\n}\n\nconst originalEvent: AnalyticsEvent = {\n  eventName: 'UserLoggedIn',\n  payload: {\n    userId: 'abc-123',\n    email: 'user@example.com',\n    preferences: {\n      theme: 'dark',\n      notifications: true\n    }\n  },\n  context: {\n    platform: 'web',\n    device: 'desktop'\n  }\n};\n\n// Get a deep property\nconst userTheme = get(originalEvent, 'payload.preferences.theme');\nconsole.log('User Theme:', userTheme); // 'dark'\n\n// Set a deep property (immutably returns a new object)\nconst updatedEvent = set(originalEvent, 'payload.preferences.notifications', false);\nconsole.log('Original notifications:', get(originalEvent, 'payload.preferences.notifications')); // true\nconsole.log('Updated notifications:', get(updatedEvent, 'payload.preferences.notifications'));   // false\n\n// Check if a value is a plain object\nconst isPayloadObject = isPlainObject(originalEvent.payload);\nconsole.log('Is payload a plain object?', isPayloadObject); // true\n\nconst isUserThemeObject = isPlainObject(userTheme);\nconsole.log('Is userTheme a plain object?', isUserThemeObject); // false\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Always capture the return value of functions like `set`: `const newObject = set(originalObject, 'path', value);`","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Use nullish coalescing or optional chaining where appropriate: `const value = get(obj, 'path') ?? 'defaultValue';` or `const value = get(obj, 'path')?.someProp;`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Migrate any direct `analytics` module utility calls to explicit imports from `analytics-utils`: `import { utility } from 'analytics-utils';`","message":"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.","severity":"deprecated","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using named imports for individual utilities: `import { get } from 'analytics-utils';`","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.","error":"TypeError: (0 , analytics_utils__WEBPACK_IMPORTED_MODULE_0__.get) is not a function"},{"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.","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.","error":"Property 'someUtil' does not exist on type 'typeof import(\"analytics-utils\")'. Did you mean 'someOtherUtil'?"}],"ecosystem":"npm"}