@rxbenefits/utils

Utility functions for data manipulation, formatting, and validation for RxBenefits applications.

Installation

npm install @rxbenefits/utils

Features

• 📅 Date & Time Utilities - Date formatting, parsing, and manipulation with moment.js
• 💰 Currency Formatting - USD currency formatting with Intl.NumberFormat
• 📝 String Utilities - Slugification, label generation, and text transformation
• 🔧 Data Transformation - Object manipulation, array grouping, and data sanitization
• 📱 Formatting Helpers - Phone, ZIP code, and file size formatting
• 🏥 Business Logic - Healthcare-specific helpers (gender, relationships, member status)
• 📄 File Utilities - MIME type detection and file type conversion

Usage

Currency Formatting

import { formatUSD } from '@rxbenefits/utils';

formatUSD(1234.56); // "$1,234.56"
formatUSD(0); // "$0.00"
formatUSD(undefined); // "N/A"
formatUSD(undefined, '-'); // "-"

Date Utilities

import { formatDate, formatDateLong, isFutureDate, isPastDate } from '@rxbenefits/utils';

formatDate('2024-01-15'); // "01/15/2024"
formatDateLong('2024-01-15'); // "01/15/2024 12:00:00 am"
isFutureDate('2025-12-31'); // true
isPastDate('2020-01-01'); // true

String Formatting

import { slugifyString, generateLabelFromField, formatPhone, formatZip } from '@rxbenefits/utils';

slugifyString('Hello World'); // "hello-world"
generateLabelFromField('firstName'); // "First Name"
generateLabelFromField('userId'); // "User ID"
formatPhone('11234567890'); // "1234567890"
formatZip('123456789'); // "12345-6789"

Data Transformation

import { emptyStringToNull, removeNullFromObject, groupArrayBy } from '@rxbenefits/utils';

// Convert empty strings to null
const data = { name: 'John', email: '' };
emptyStringToNull(data);
// data is now { name: 'John', email: null }

// Remove null/undefined/empty string values
const obj = { a: 1, b: null, c: '', d: 'test' };
removeNullFromObject(obj);
// obj is now { a: 1, d: 'test' }

// Group array by key
const items = [
  { id: 1, category: 'A' },
  { id: 2, category: 'B' },
  { id: 3, category: 'A' },
];
const grouped = groupArrayBy(items, (item) => item.category);
// Map { 'A' => [item1, item3], 'B' => [item2] }

File Utilities

import {
  formatBytes,
  fileNameToFileType,
  createAcceptedFileTypeString,
  PDF_MIME_TYPES,
  XLSX_MIME_TYPES,
} from '@rxbenefits/utils';

formatBytes(1024); // "1 KB"
formatBytes(1048576); // "1 MB"
formatBytes(1536, 2); // "1.5 KB"

fileNameToFileType('report.pdf'); // "PDF"
fileNameToFileType('data.xlsx'); // "Excel"

createAcceptedFileTypeString([PDF_MIME_TYPES, XLSX_MIME_TYPES]);
// "application/pdf,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

Business Logic Helpers

import {
  getGenderLabel,
  getRelationshipLabel,
  getFriendlyUserType,
  isMemberActive,
} from '@rxbenefits/utils';

getGenderLabel('M'); // "Male"
getGenderLabel('F'); // "Female"

getRelationshipLabel(1); // "Subscriber"
getRelationshipLabel(3); // "Child"

getFriendlyUserType('i' as any); // "Internal"
getFriendlyUserType('b' as any); // "Broker"

isMemberActive({ processStatus: 1 }); // true
isMemberActive({
  processStatus: 9,
  expirationDate: '2025-12-31',
}); // true

API Reference

Date & Time

• formatDate(date) - Format date as MM/DD/YYYY (UTC)
• formatUTCDate(date) - Format date as MM/DD/YYYY (local)
• formatDateLong(date) - Format date with time
• isFutureDate(date) - Check if date is in the future
• isPastDate(date) - Check if date is in the past
• isToday(date) - Check if date is today
• isTodayOrFutureDate(date) - Check if date is today or future
• isDateTodayOrPastDate(current, date) - For Ant Design DatePicker
• getFromNow(date) - Get relative time string

Currency

• formatUSD(amount, fallbackText?) - Format amount as USD currency

String Manipulation

• slugifyString(string) - Convert string to URL-friendly slug
• generateLabelFromField(fieldName) - Convert camelCase to Title Case

Phone & ZIP

• formatPhone(phone) - Format phone number
• formatZip(zip) - Format ZIP code with hyphen

File Operations

• formatBytes(bytes, decimals?) - Format bytes to human-readable size
• fileNameToFileType(fileName) - Get user-friendly file type from filename
• createAcceptedFileTypeString(types) - Create accept string for file inputs
• MIME type constants: CSV_MIME_TYPES, PDF_MIME_TYPES, XLSX_MIME_TYPES, etc.

Data Transformation

• emptyStringToNull(object) - Convert empty strings to null (mutates object)
• removeNullFromObject(obj) - Remove null/undefined/empty values (mutates object)
• groupArrayBy(array, keyGetter) - Group array by key function, returns Map
• objectToSearchParams(obj) - Convert object to URL search parameters
• parseParamString(paramString) - Parse URL parameter string

Business Logic

• getGenderLabel(gender) - Get label for gender code ('M'/'F')
• getRelationshipLabel(relationship) - Get label for relationship code (1-6)
• getFriendlyUserType(userType) - Get label for user type ('i'/'b'/'c')
• getAgeFromDOB(dob) - Calculate age from date of birth
• getRolesByApplication(applications) - Extract roles by application
• isMemberActive(member) - Check if member is active
• identifyResource(resource) - Identify resource type from URL

UI Helpers

• calculateDynamicTableColumnWidth(config) - Calculate dynamic table column width

Migration Notes

Int32Validator

⚠️ Breaking Change: The Int32Validator function has been moved from @rxbenefits/utils to @rxbenefits/constants.

Before:

import { Int32Validator } from '@rxbenefits/utils';

After:

import { Int32Validator } from '@rxbenefits/constants';

For backwards compatibility, @rxbenefits/utils v1.x re-exports Int32Validator from @rxbenefits/constants with a deprecation notice. This re-export will be removed in v2.0.0.

Current (v1.x - deprecated):

import { Int32Validator } from '@rxbenefits/utils'; // Still works but deprecated

Recommended:

import { Int32Validator } from '@rxbenefits/constants';

Peer Dependencies

This package requires the following peer dependencies:

• @rxbenefits/types ^1.0.0
• @rxbenefits/constants ^1.0.0
• moment ^2.29.0
• typescript >=5.0.0

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Lint
npm run lint

# Build
npm run build

# Run all validations
npm run validate

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

MIT © RxBenefits

Support

For issues and questions:

• 🐛 Report bugs
• 💬 Discussions
• 📧 Contact: [email protected]

Related Packages

• @rxbenefits/types - TypeScript type definitions
• @rxbenefits/constants - Application constants
• @rxbenefits/ui - UI component library