@onivoro/isomorphic-common

Common utilities, functions, types, and constants shared between browser and server environments in the Onivoro monorepo. This library provides essential building blocks for TypeScript applications with a focus on type safety and consistent behavior across different runtime environments.

Installation

1npm install @onivoro/isomorphic-common

Features

• Isomorphic Design: Works identically in browser and Node.js environments
• String Manipulation: Case conversion, formatting, and validation utilities
• Array Operations: Chunking, sorting, deduplication, and transformation functions
• Date/Time Utilities: Calendar operations, offset calculations, and time constants
• Financial Functions: Currency formatting and money calculations
• Type Utilities: TypeScript type helpers and interfaces
• Validation Functions: Data validation and parsing utilities
• Testing Helpers: Mock functions and test arrangement utilities
• Constants: Authentication headers, regex patterns, and time constants

Constants

Authentication Headers

1import { apiKeyHeader } from '@onivoro/isomorphic-common';
2
3// Use in HTTP requests
4const headers = {
5  [apiKeyHeader]: 'your-api-key' // 'x-api-key'
6};

Time Constants

1import { MILLIS_PER_DAY, MILLIS_PER_HOUR, MILLIS_PER_MINUTE } from '@onivoro/isomorphic-common';
2
3// Time constants (calculated from MILLIS_PER_MINUTE base)
4const hoursInDay = MILLIS_PER_DAY / MILLIS_PER_HOUR; // 24
5const minutesInHour = MILLIS_PER_HOUR / MILLIS_PER_MINUTE; // 60
6
7// Set timeouts
8setTimeout(() => {}, MILLIS_PER_MINUTE); // 1 minute timeout

Regular Expressions

1import { 
2  email, 
3  phone, 
4  zip, 
5  v4, 
6  dateIso8601, 
7  numeric,
8  ssn,
9  ein 
10} from '@onivoro/isomorphic-common';
11
12// Validate email
13const isValidEmail = email.test('user@example.com'); // true
14
15// Validate phone number (format: 123-456-7890)
16const isValidPhone = phone.test('123-456-7890'); // true
17
18// Validate ZIP code (5 digits)
19const isValidZip = zip.test('12345'); // true
20
21// Validate UUID v4
22const isValidUuid = v4.test('550e8400-e29b-41d4-a716-446655440000'); // true
23
24// Validate ISO date (YYYY-MM-DD)
25const isValidDate = dateIso8601.test('2023-12-31'); // true

String Functions

Case Conversion

1import { camelCase, kebabCase, snakeCase } from '@onivoro/isomorphic-common';
2
3// camelCase(string: string): string
4camelCase('hello world'); // 'helloWorld'
5camelCase('--foo-bar--'); // 'fooBar'
6camelCase('__FOO_BAR__'); // 'fooBar'
7
8// kebabCase(string: string): string
9kebabCase('Hello World'); // 'hello-world'
10kebabCase('fooBar'); // 'foo-bar'
11
12// snakeCase(string: string): string
13snakeCase('Hello World'); // 'hello_world'
14snakeCase('fooBar'); // 'foo_bar'

Array Functions

Array Manipulation

1import { 
2  chunk, 
3  removeElementAtIndex, 
4  toUniqueArray 
5} from '@onivoro/isomorphic-common';
6
7// chunk<T>(array: T[], numDivisions: number): T[][]
8// Divides array into N divisions (NOT chunks of size N)
9chunk([1, 2, 3, 4, 5, 6], 3); // [[1, 2], [3, 4], [5, 6]] - 3 divisions
10chunk([1, 2, 3, 4, 5], 2); // [[1, 2, 3], [4, 5]] - 2 divisions
11
12// removeElementAtIndex<T>(array: T[], indexToRemove: number): T[]
13removeElementAtIndex(['a', 'b', 'c'], 1); // ['a', 'c']
14
15// toUniqueArray<TElement>(elements: TElement[]): TElement[]
16toUniqueArray([1, 2, 2, 3, 3, 4]); // [1, 2, 3, 4]

Sorting Functions

1import { 
2  sortByName, 
3  sortById, 
4  sortNumbers 
5} from '@onivoro/isomorphic-common';
6
7// sortByName<TEntity extends { name: string }>(a: TEntity, b: TEntity): number
8const users = [{ name: 'Bob' }, { name: 'Alice' }];
9users.sort(sortByName); // [{ name: 'Alice' }, { name: 'Bob' }]
10
11// sortById<TEntity extends { id: string }>(a: TEntity, b: TEntity): number
12const items = [{ id: '3' }, { id: '1' }, { id: '2' }];
13items.sort(sortById); // [{ id: '1' }, { id: '2' }, { id: '3' }]
14
15// sortNumbers(a: number, b: number): number
16const numbers = [3, 1, 4, 1, 5];
17numbers.sort(sortNumbers); // [1, 1, 3, 4, 5]

Date/Time Functions

Date Operations

1import { 
2  addOffset, 
3  subtractOffset, 
4  getDateRangeForMonth
5} from '@onivoro/isomorphic-common';
6
7// addOffset(input: string | Date | undefined | null): Date | undefined
8const date = new Date('2023-01-15');
9const withOffset = addOffset(date); // Adds timezone offset
10
11// subtractOffset(input: string | Date | undefined | null): Date | undefined
12const withoutOffset = subtractOffset(date); // Subtracts timezone offset
13
14// getDateRangeForMonth(year: number, month: number): {startDate: Date, endDate: Date}
15const { startDate, endDate } = getDateRangeForMonth(2023, 0); // January 2023 (month 0-indexed)

Date Utilities

1import { 
2  isValidDate, 
3  parseBool
4} from '@onivoro/isomorphic-common';
5
6// isValidDate(dateString: string | Date): Date | undefined
7const validDate = isValidDate('2023-01-15'); // Date object
8const invalidDate = isValidDate('invalid'); // undefined
9
10// parseBool(asc: string | boolean | null | undefined): boolean
11parseBool('true'); // true
12parseBool('false'); // false
13parseBool(true); // true
14parseBool(null); // false

Financial Functions

1import { 
2  formatUsd, 
3  money, 
4  toDollarsAndCents, 
5  round 
6} from '@onivoro/isomorphic-common';
7
8// formatUsd(rawAmount?: number | string): string
9formatUsd(1234.56); // '$1,234.56'
10formatUsd('1234.56'); // '$1,234.56'
11formatUsd(); // '$0.00'
12
13// money(rawValue: number | string): string | undefined
14money(19.99); // '$19.99'
15money('abc'); // undefined
16
17// toDollarsAndCents(input: string | number): string
18toDollarsAndCents(19.99); // 'nineteen dollars and ninety-nine cents'
19toDollarsAndCents(20); // 'twenty dollars'
20
21// round(numberToRound: number, scalingFactor: number): number
22round(19.999, 100); // 20.00 (rounds to nearest cent)
23round(19.994, 100); // 19.99

Data Transformation

Enum Utilities

1import { 
2  mapEnumToOptions
3} from '@onivoro/isomorphic-common';
4
5enum Status {
6  ACTIVE = 'active',
7  INACTIVE = 'inactive',
8  PENDING = 'pending'
9}
10
11// mapEnumToOptions<TEntity extends object>(enumeration: TEntity, includeBlank = true)
12const options = mapEnumToOptions(Status);
13// [{ display: '', value: '' }, { display: 'ACTIVE', value: 'active' }, ...]
14
15const optionsNoBlank = mapEnumToOptions(Status, false);
16// [{ display: 'ACTIVE', value: 'active' }, ...]

Entity Utilities

1import { getUserFullName } from '@onivoro/isomorphic-common';
2
3// getUserFullName(user: TNameable | undefined): string
4const user = { firstName: 'John', lastName: 'Doe' };
5getUserFullName(user); // 'John Doe'
6getUserFullName(undefined); // 'undefined undefined'

JSON Utilities

1import { 
2  tryJsonParse, 
3  tryJsonStringify 
4} from '@onivoro/isomorphic-common';
5
6// tryJsonParse<T>(parseable: string | null | undefined): T | null
7const parsed = tryJsonParse<{name: string}>('{"name":"John"}'); // {name: 'John'}
8const failed = tryJsonParse('invalid json'); // null
9
10// tryJsonStringify<T>(object: T | null | undefined, fmtr?: any, spaces?: number): string | null
11const json = tryJsonStringify({name: 'John'}); // '{"name":"John"}'
12const formatted = tryJsonStringify({name: 'John'}, null, 2); // Pretty formatted JSON

Utility Functions

1import { sleep } from '@onivoro/isomorphic-common';
2
3// sleep(milliseconds = 0): Promise<void>
4await sleep(1000); // Wait 1 second
5await sleep(); // Wait 0 milliseconds (next tick)

Type Definitions

Interfaces

1import { 
2  ILookup, 
3  TNameable 
4} from '@onivoro/isomorphic-common';
5
6// Lookup interface for key-value pairs
7const lookup: ILookup<string, number> = {
8  display: 'Option 1',
9  value: 1
10};
11
12// Nameable type
13const user: TNameable = {
14  firstName: 'John',
15  lastName: 'Doe'
16};

License

This library is licensed under the MIT License. See the LICENSE file in this package for details.