@onivoro/isomorphic-common 22.0.7 → 24.0.1

package/README.md

@@ -0,0 +1,289 @@
+# @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
+
+```bash
+npm 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
+```typescript
+import { apiKeyHeader } from '@onivoro/isomorphic-common';
+
+// Use in HTTP requests
+const headers = {
+  [apiKeyHeader]: 'your-api-key' // 'x-api-key'
+};
+```
+
+### Time Constants
+```typescript
+import { MILLIS_PER_DAY, MILLIS_PER_HOUR, MILLIS_PER_MINUTE } from '@onivoro/isomorphic-common';
+
+// Time constants (calculated from MILLIS_PER_MINUTE base)
+const hoursInDay = MILLIS_PER_DAY / MILLIS_PER_HOUR; // 24
+const minutesInHour = MILLIS_PER_HOUR / MILLIS_PER_MINUTE; // 60
+
+// Set timeouts
+setTimeout(() => {}, MILLIS_PER_MINUTE); // 1 minute timeout
+```
+
+### Regular Expressions
+```typescript
+import { 
+  email, 
+  phone, 
+  zip, 
+  v4, 
+  dateIso8601, 
+  numeric,
+  ssn,
+  ein 
+} from '@onivoro/isomorphic-common';
+
+// Validate email
+const isValidEmail = email.test('user@example.com'); // true
+
+// Validate phone number (format: 123-456-7890)
+const isValidPhone = phone.test('123-456-7890'); // true
+
+// Validate ZIP code (5 digits)
+const isValidZip = zip.test('12345'); // true
+
+// Validate UUID v4
+const isValidUuid = v4.test('550e8400-e29b-41d4-a716-446655440000'); // true
+
+// Validate ISO date (YYYY-MM-DD)
+const isValidDate = dateIso8601.test('2023-12-31'); // true
+```
+
+## String Functions
+
+### Case Conversion
+```typescript
+import { camelCase, kebabCase, snakeCase } from '@onivoro/isomorphic-common';
+
+// camelCase(string: string): string
+camelCase('hello world'); // 'helloWorld'
+camelCase('--foo-bar--'); // 'fooBar'
+camelCase('__FOO_BAR__'); // 'fooBar'
+
+// kebabCase(string: string): string
+kebabCase('Hello World'); // 'hello-world'
+kebabCase('fooBar'); // 'foo-bar'
+
+// snakeCase(string: string): string
+snakeCase('Hello World'); // 'hello_world'
+snakeCase('fooBar'); // 'foo_bar'
+```
+
+## Array Functions
+
+### Array Manipulation
+```typescript
+import { 
+  chunk, 
+  removeElementAtIndex, 
+  toUniqueArray 
+} from '@onivoro/isomorphic-common';
+
+// chunk<T>(array: T[], numDivisions: number): T[][]
+// Divides array into N divisions (NOT chunks of size N)
+chunk([1, 2, 3, 4, 5, 6], 3); // [[1, 2], [3, 4], [5, 6]] - 3 divisions
+chunk([1, 2, 3, 4, 5], 2); // [[1, 2, 3], [4, 5]] - 2 divisions
+
+// removeElementAtIndex<T>(array: T[], indexToRemove: number): T[]
+removeElementAtIndex(['a', 'b', 'c'], 1); // ['a', 'c']
+
+// toUniqueArray<TElement>(elements: TElement[]): TElement[]
+toUniqueArray([1, 2, 2, 3, 3, 4]); // [1, 2, 3, 4]
+```
+
+### Sorting Functions
+```typescript
+import { 
+  sortByName, 
+  sortById, 
+  sortNumbers 
+} from '@onivoro/isomorphic-common';
+
+// sortByName<TEntity extends { name: string }>(a: TEntity, b: TEntity): number
+const users = [{ name: 'Bob' }, { name: 'Alice' }];
+users.sort(sortByName); // [{ name: 'Alice' }, { name: 'Bob' }]
+
+// sortById<TEntity extends { id: string }>(a: TEntity, b: TEntity): number
+const items = [{ id: '3' }, { id: '1' }, { id: '2' }];
+items.sort(sortById); // [{ id: '1' }, { id: '2' }, { id: '3' }]
+
+// sortNumbers(a: number, b: number): number
+const numbers = [3, 1, 4, 1, 5];
+numbers.sort(sortNumbers); // [1, 1, 3, 4, 5]
+```
+
+## Date/Time Functions
+
+### Date Operations
+```typescript
+import { 
+  addOffset, 
+  subtractOffset, 
+  getDateRangeForMonth
+} from '@onivoro/isomorphic-common';
+
+// addOffset(input: string | Date | undefined | null): Date | undefined
+const date = new Date('2023-01-15');
+const withOffset = addOffset(date); // Adds timezone offset
+
+// subtractOffset(input: string | Date | undefined | null): Date | undefined
+const withoutOffset = subtractOffset(date); // Subtracts timezone offset
+
+// getDateRangeForMonth(year: number, month: number): {startDate: Date, endDate: Date}
+const { startDate, endDate } = getDateRangeForMonth(2023, 0); // January 2023 (month 0-indexed)
+```
+
+### Date Utilities
+```typescript
+import { 
+  isValidDate, 
+  parseBool
+} from '@onivoro/isomorphic-common';
+
+// isValidDate(dateString: string | Date): Date | undefined
+const validDate = isValidDate('2023-01-15'); // Date object
+const invalidDate = isValidDate('invalid'); // undefined
+
+// parseBool(asc: string | boolean | null | undefined): boolean
+parseBool('true'); // true
+parseBool('false'); // false
+parseBool(true); // true
+parseBool(null); // false
+```
+
+## Financial Functions
+
+```typescript
+import { 
+  formatUsd, 
+  money, 
+  toDollarsAndCents, 
+  round 
+} from '@onivoro/isomorphic-common';
+
+// formatUsd(rawAmount?: number | string): string
+formatUsd(1234.56); // '$1,234.56'
+formatUsd('1234.56'); // '$1,234.56'
+formatUsd(); // '$0.00'
+
+// money(rawValue: number | string): string | undefined
+money(19.99); // '$19.99'
+money('abc'); // undefined
+
+// toDollarsAndCents(input: string | number): string
+toDollarsAndCents(19.99); // 'nineteen dollars and ninety-nine cents'
+toDollarsAndCents(20); // 'twenty dollars'
+
+// round(numberToRound: number, scalingFactor: number): number
+round(19.999, 100); // 20.00 (rounds to nearest cent)
+round(19.994, 100); // 19.99
+```
+
+## Data Transformation
+
+### Enum Utilities
+```typescript
+import { 
+  mapEnumToOptions
+} from '@onivoro/isomorphic-common';
+
+enum Status {
+  ACTIVE = 'active',
+  INACTIVE = 'inactive',
+  PENDING = 'pending'
+}
+
+// mapEnumToOptions<TEntity extends object>(enumeration: TEntity, includeBlank = true)
+const options = mapEnumToOptions(Status);
+// [{ display: '', value: '' }, { display: 'ACTIVE', value: 'active' }, ...]
+
+const optionsNoBlank = mapEnumToOptions(Status, false);
+// [{ display: 'ACTIVE', value: 'active' }, ...]
+```
+
+### Entity Utilities
+```typescript
+import { getUserFullName } from '@onivoro/isomorphic-common';
+
+// getUserFullName(user: TNameable | undefined): string
+const user = { firstName: 'John', lastName: 'Doe' };
+getUserFullName(user); // 'John Doe'
+getUserFullName(undefined); // 'undefined undefined'
+```
+
+## JSON Utilities
+
+```typescript
+import { 
+  tryJsonParse, 
+  tryJsonStringify 
+} from '@onivoro/isomorphic-common';
+
+// tryJsonParse<T>(parseable: string | null | undefined): T | null
+const parsed = tryJsonParse<{name: string}>('{"name":"John"}'); // {name: 'John'}
+const failed = tryJsonParse('invalid json'); // null
+
+// tryJsonStringify<T>(object: T | null | undefined, fmtr?: any, spaces?: number): string | null
+const json = tryJsonStringify({name: 'John'}); // '{"name":"John"}'
+const formatted = tryJsonStringify({name: 'John'}, null, 2); // Pretty formatted JSON
+```
+
+## Utility Functions
+
+```typescript
+import { sleep } from '@onivoro/isomorphic-common';
+
+// sleep(milliseconds = 0): Promise<void>
+await sleep(1000); // Wait 1 second
+await sleep(); // Wait 0 milliseconds (next tick)
+```
+
+## Type Definitions
+
+### Interfaces
+```typescript
+import { 
+  ILookup, 
+  TNameable 
+} from '@onivoro/isomorphic-common';
+
+// Lookup interface for key-value pairs
+const lookup: ILookup<string, number> = {
+  display: 'Option 1',
+  value: 1
+};
+
+// Nameable type
+const user: TNameable = {
+  firstName: 'John',
+  lastName: 'Doe'
+};
+```
+
+## License
+
+MIT

package/jest.config.ts

@@ -0,0 +1,11 @@
+/* eslint-disable */
+export default {
+  displayName: 'lib-isomorphic-common',
+  preset: '../../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../../coverage/libs/isomorphic/common',
+};

package/package.json

@@ -1,41 +1,10 @@
 {
-    "name": "@onivoro/isomorphic-common",
-    "version": "22.0.7",
-    "repository": {
-        "url": "git+https://github.com/onivoro/isomorphic-common.git"
-    },
-    "main": "dist/cjs/index.js",
-    "module": "dist/esm/index.js",
-    "types": "dist/types/index.d.ts",
-    "files": [
-        "dist/*"
-    ],
-    "scripts": {
-        "onx": "onx",
-        "build": "onx Build",
-        "deploy": "onx Publish",
-        "test": "onx Test",
-        "update": "onx Update"
-    },
-    "exports": {
-        ".": {
-            "types": "./dist/types/index.d.ts",
-            "require": "./dist/cjs/index.js",
-            "import": "./dist/esm/index.js",
-            "default": "./dist/esm/lib.js"
-        }
-    },
-    "onx": {
-        "platform": "isomorphic",
-        "module": "commonjs"
-    },
-    "devDependencies": {
-        "@onivoro/cli": "^22.0.8",
-        "@types/jest": "*",
-        "typescript": "*"
-    },
-    "engines": {
-        "node": "22.10.0",
-        "npm": "10.9.0"
-    }
+  "name": "@onivoro/isomorphic-common",
+  "version": "24.0.1",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
 }

package/project.json

@@ -0,0 +1,23 @@
+{
+  "name": "lib-isomorphic-common",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/isomorphic/common/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/isomorphic/common",
+        "main": "libs/isomorphic/common/src/index.ts",
+        "tsConfig": "libs/isomorphic/common/tsconfig.lib.json",
+        "assets": [
+          "libs/isomorphic/common/README.md",
+          "libs/isomorphic/common/package.json"
+        ],
+        "declaration": true
+      }
+    }
+  },
+  "tags": []
+}

package/{dist/cjs/index.d.ts → src/index.ts}

@@ -1,7 +1,43 @@
+export * from './lib/constants/api-id-header.constant';
+export * from './lib/constants/api-key-header.constant';
+export * from './lib/constants/auth-cookie-name.constant';
+export * from './lib/constants/regexes.constant';
+
+export * from './lib/functions/arrange-act-assert.function';
+export * from './lib/functions/mock-calls.function';
+
+export * from './lib/functions/chunk.function';
+export * from './lib/functions/format-usd.function';
+export * from './lib/functions/get-date-last-month.function';
+export * from './lib/functions/get-date-range-for-month.function';
+export * from './lib/functions/get-user-full-name.function';
+export * from './lib/functions/is-valid-date.function';
+export * from './lib/functions/map-entities-to-options.function';
+export * from './lib/functions/map-enum-to-array-of-values.function';
+export * from './lib/functions/map-enum-to-lookup-array.function';
+export * from './lib/functions/map-enum-to-options.function';
+export * from './lib/functions/remove-element-at-index.function';
+export * from './lib/functions/round.function';
+export * from './lib/functions/sort-by-created-at.function';
+export * from './lib/functions/sort-by-full-name.function';
+export * from './lib/functions/sort-by-id.function';
+export * from './lib/functions/sort-by-name.function';
+export * from './lib/functions/sort-numbers.function';
+export * from './lib/functions/split-date-range-into-days.function';
+export * from './lib/functions/use-date.function';
+
+export * from './lib/types/access-token.interface';
+export * from './lib/types/company.type';
+export * from './lib/types/createable.type';
+export * from './lib/types/keys-of.type';
+export * from './lib/types/lookup.interface';
+export * from './lib/types/nameable.type';
+
 export * from './lib/constants/millis-per-day.constant';
 export * from './lib/constants/millis-per-hour.constant';
 export * from './lib/constants/millis-per-minute.constant';
 export * from './lib/constants/regexes.constant';
+
 export * from './lib/functions/add-offset.function';
 export * from './lib/functions/camel-case.function';
 export * from './lib/functions/convert-object-to-literal.function';
@@ -37,7 +73,8 @@ export * from './lib/functions/try-parse-date.function';
 export * from './lib/functions/unicode-words.const';
 export * from './lib/functions/upper-first.function';
 export * from './lib/functions/words.function';
-export * from './lib/interfaces/axios-wrapped-nest-exception.interface';
-export * from './lib/interfaces/entity-provider.interface';
-export * from './lib/interfaces/keys-of.type';
-export * from './lib/interfaces/lookup.interface';
+
+export * from './lib/types/axios-wrapped-nest-exception.interface';
+export * from './lib/types/entity-provider.interface';
+export * from './lib/types/keys-of.type';
+export * from './lib/types/lookup.interface';

package/src/lib/constants/api-id-header.constant.ts

@@ -0,0 +1 @@
+export const apiIdHeader = 'x-api-id';

package/src/lib/constants/api-key-header.constant.ts

@@ -0,0 +1 @@
+export const apiKeyHeader = 'x-api-key';

package/src/lib/constants/auth-cookie-name.constant.ts

@@ -0,0 +1,2 @@
+// TODO: REMOVE THIS BAD PATTERN OF HAVING LOWER LEVEL LIBS AWARE OF HIGHER ORDER LIBS/APPS
+export const authCookieName = 'token';

package/src/lib/constants/millis-per-day.constant.ts

@@ -0,0 +1,3 @@
+import { MILLIS_PER_HOUR } from "./millis-per-hour.constant";
+
+export const MILLIS_PER_DAY = MILLIS_PER_HOUR * 24;

package/src/lib/constants/millis-per-hour.constant.ts

@@ -0,0 +1,3 @@
+import { MILLIS_PER_MINUTE } from "./millis-per-minute.constant";
+
+export const MILLIS_PER_HOUR = MILLIS_PER_MINUTE * 60;

package/src/lib/constants/millis-per-minute.constant.ts

@@ -0,0 +1 @@
+export const MILLIS_PER_MINUTE = 1000 * 60;

package/src/lib/constants/regexes.constant.ts

@@ -0,0 +1,30 @@
+export const oneOrMoreSpaces = /\s{1,}/g;
+export const multipleSpaces = /\s{2,}/g;
+export const comma = /,/g;
+export const dashesLettersNumbers = /^([a-z]|-|\d)*$/i;
+export const dashesLettersNumbersSpaces = /^([a-z]|-|\s|\d)*$/i;
+export const zip = /^\d{5}$/;
+export const phone = /^\d{3}-\d{3}-\d{4}$/;
+export const phonePlusOne = /^\+1\d{10}$/;
+export const code = /^\d{6}$/;
+export const url = /(https?:\/\/|https?:\/\/).*\..+/;
+export const protocol = /https?:\/\/|https?:\/\//;
+export const firstSpaceLast = /[a-z]+\s[a-z]+([a-z]|')+[a-z]+/i;
+export const passwordNumber = /\d/;
+export const passwordUpper = /[A-Z]/;
+export const passwordLower = /[a-z]/;
+export const passwordSpecial = /\^|\$|\*|\.|\?|-|!|@|#|%|>|<|:|;|_|~|\+|=/;
+export const ssn = /^\d{3}-\d{2}-\d{4}$/;
+export const numeric = /^(\d|\.)*$/;
+export const duns = /^\d{9}$/;
+export const lastFourSocial = /^\d{4}$/;
+export const ein = /^\d{2}-\d{7}$/;
+export const stateShort = /^[A-Z]{2}$/;
+export const email = /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
+export const domain = /^(?!:\/\/)([a-zA-Z0-9-_]{1,63}\.)+[a-zA-Z]{2,63}$/;
+export const emailDomain = /^[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+export const v4 = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/;
+export const dateIso8601 = /^\d{4}-\d{1,2}-\d{1,2}$/;
+export const dateIso8601WithTime = /^\d{4}-\d{1,2}-\d{1,2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+export const decimalRegex = /(\d|\.)/g;
+export const slashR = /\r/g;

package/src/lib/functions/__snapshots__/chunk.function.spec.ts.snap

@@ -0,0 +1,94 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`chunk given 1, returns an array of arrays 1`] = `
+[
+  [
+    "one",
+    "two",
+    "three",
+    "four",
+    "five",
+    "six",
+    "seven",
+    "eight",
+  ],
+]
+`;
+
+exports[`chunk given 2, returns an array of arrays 1`] = `
+[
+  [
+    "one",
+    "two",
+    "three",
+    "four",
+  ],
+  [
+    "five",
+    "six",
+    "seven",
+    "eight",
+  ],
+]
+`;
+
+exports[`chunk given 3, returns an array of arrays 1`] = `
+[
+  [
+    "one",
+    "two",
+    "three",
+  ],
+  [
+    "four",
+    "five",
+    "six",
+  ],
+  [
+    "seven",
+    "eight",
+  ],
+]
+`;
+
+exports[`chunk given 4, returns an array of arrays 1`] = `
+[
+  [
+    "one",
+    "two",
+  ],
+  [
+    "three",
+    "four",
+  ],
+  [
+    "five",
+    "six",
+  ],
+  [
+    "seven",
+    "eight",
+  ],
+]
+`;
+
+exports[`chunk given 5, returns an array of arrays 1`] = `
+[
+  [
+    "one",
+    "two",
+  ],
+  [
+    "three",
+    "four",
+  ],
+  [
+    "five",
+    "six",
+  ],
+  [
+    "seven",
+    "eight",
+  ],
+]
+`;

package/src/lib/functions/__snapshots__/split-date-range-into-days.function.spec.ts.snap

@@ -0,0 +1,50 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`splitDateRangeIntoDays given {"from":"","to":""}, returns an array of days 1`] = `[]`;
+
+exports[`splitDateRangeIntoDays given {"from":"2024-01-01","to":"2024-01-01"}, returns an array of days 1`] = `
+[
+  "2024-01-01",
+]
+`;
+
+exports[`splitDateRangeIntoDays given {"from":"2024-01-01","to":"2024-02-01"}, returns an array of days 1`] = `
+[
+  "2024-01-01",
+  "2024-01-02",
+  "2024-01-03",
+  "2024-01-04",
+  "2024-01-05",
+  "2024-01-06",
+  "2024-01-07",
+  "2024-01-08",
+  "2024-01-09",
+  "2024-01-10",
+  "2024-01-11",
+  "2024-01-12",
+  "2024-01-13",
+  "2024-01-14",
+  "2024-01-15",
+  "2024-01-16",
+  "2024-01-17",
+  "2024-01-18",
+  "2024-01-19",
+  "2024-01-20",
+  "2024-01-21",
+  "2024-01-22",
+  "2024-01-23",
+  "2024-01-24",
+  "2024-01-25",
+  "2024-01-26",
+  "2024-01-27",
+  "2024-01-28",
+  "2024-01-29",
+  "2024-01-30",
+  "2024-01-31",
+  "2024-02-01",
+]
+`;
+
+exports[`splitDateRangeIntoDays given {"from":"2025-01-01","to":""}, returns an array of days 1`] = `[]`;
+
+exports[`splitDateRangeIntoDays given {"from":"asdf","to":"2345"}, returns an array of days 1`] = `[]`;

package/src/lib/functions/add-offset.function.spec.ts

@@ -0,0 +1,12 @@
+import { addOffset } from './add-offset.function';
+
+describe('addOffset', () => {
+    describe('GIVEN input is partial or full ISO8601', () => {
+        it.each([
+            '2023-12-23',
+            '2023-12-23T00:00:00.000',
+        ])('%j', (input) => {
+            expect(addOffset(input)).toMatchSnapshot();
+        });
+    });
+});

package/src/lib/functions/add-offset.function.ts

@@ -0,0 +1,14 @@
+import { MILLIS_PER_MINUTE } from '../constants/millis-per-minute.constant';
+import { tryParseDate } from './try-parse-date.function';
+
+export function addOffset(input: string | Date | undefined | null): Date | undefined {
+    const parsed = tryParseDate(input);
+
+    if(!parsed) {
+        return;
+    }
+
+    const offset = (parsed).getTimezoneOffset();
+
+    return new Date(parsed.valueOf() + offset * MILLIS_PER_MINUTE);
+}

package/src/lib/functions/arrange-act-assert.function.ts

@@ -0,0 +1,23 @@
+// YOU MUST AWAIT THIS FUNCTION WHEN INVOKING IT!!!
+
+// TODO: PUT THIS IN A TEST-ONLY LIBRARY => LIBS/ISO/JEST
+
+export async function arrangeActAssert<TArrangeOutput, TActOutput>({ arrange, act, assert }: { arrange: () => TArrangeOutput, act: (_: TArrangeOutput) => TActOutput, assert: (_: TArrangeOutput & { result: TActOutput }) => any }) {
+    const arrangeOutput = arrange();
+
+    const actInput = isPromise(arrangeOutput) ? await arrangeOutput : arrangeOutput;
+
+    const actOutput = act(actInput);
+
+    const assertInput = isPromise(actOutput) ? await actOutput : actOutput;
+
+    const assertOutput = assert({ ...actInput, result: assertInput });
+
+    const returnValue = isPromise(assertOutput) ? await assertOutput : assertOutput;
+
+    return returnValue;
+}
+
+function isPromise(value: any) {
+    return (typeof value?.then) === 'function';
+}