@sdflc/utils

@sdflc/utils

A collection of TypeScript utility functions for common tasks including address formatting, array manipulation, color helpers, unit conversions, geolocation math, logging, performance measurement, string processing, and more.

---

Installation

npm install @sdflc/utils

---

Table of Contents

• Addresses
• Arrays
• Colors
• Constants
• Converters
• Geo
• Languages
• Logger
• MeasureTool
• Numbers
• Objects
• Strings
• String Helpers
• StrOrderHelpers
• Transformers
• URL Params

---

Addresses

import { formatAddressShort, formatAddressFull } from '@sdflc/utils';

formatAddressShort(address)

Formats an AddressData object into a short display string suitable for place auto-fill. Includes address1, city, and region.

formatAddressShort({ address1: '123 Main St', city: 'Calgary', region: 'AB' });
// => '123 Main St, Calgary, AB'

formatAddressShort(null); // => ''

formatAddressFull(address)

Formats an AddressData object into a full display string. Includes address1, city, region, postalCode, and country.

formatAddressFull({
  address1: '123 Main St',
  city: 'Calgary',
  region: 'AB',
  postalCode: 'T2P 1J9',
  country: 'Canada',
});
// => '123 Main St, Calgary, AB T2P 1J9, Canada'

---

Arrays

import { arrayToObject, arrToUpperCase, arrToLowerCase, arrToChunks } from '@sdflc/utils';

arrayToObject(arr, nameKey, valueKey)

Converts an array of objects into a plain object using nameKey for property names and valueKey for values.

const arr = [
  { name: 'status', value: 'active' },
  { name: 'role', value: 'admin' },
];
arrayToObject(arr, 'name', 'value');
// => { status: 'active', role: 'admin' }

arrToUpperCase(arr)

Uppercases every string in the array. Null/undefined items become ''.

arrToUpperCase(['hello', 'world']); // => ['HELLO', 'WORLD']

arrToLowerCase(arr)

Lowercases every string in the array. Null/undefined items become ''.

arrToLowerCase(['HELLO', 'WORLD']); // => ['hello', 'world']

arrToChunks(arr, chunkSize)

Splits an array into sequential chunks of chunkSize. Returns the original array if chunkSize is less than 1 or NaN.

arrToChunks([1, 2, 3, 4, 5], 2); // => [[1, 2], [3, 4], [5]]
arrToChunks([1, 2, 3], 0); // => [1, 2, 3]

---

Colors

import { getRandomHexColor, getMostContrastingColor } from '@sdflc/utils';

getRandomHexColor()

Returns a random hex color string in #RRGGBB format, including #000000 and #FFFFFF.

getRandomHexColor(); // => '#a3f2c1'

getMostContrastingColor(hex)

Returns either #000000 or #FFFFFF — whichever has the higher WCAG contrast ratio against the given background color. Supports #RGB, #RGBA, #RRGGBB, and #RRGGBBAA formats. Alpha is preserved in the output if present in the input.

getMostContrastingColor('#000000'); // => '#FFFFFF'
getMostContrastingColor('#FFFFFF'); // => '#000000'
getMostContrastingColor('#1a1a2e'); // => '#FFFFFF'
getMostContrastingColor('#000000aa'); // => '#FFFFFFaa'

---

Constants

import {
  VALUE_TYPES,
  STATUSES,
  ACCESS_RIGHTS,
  SORT_ORDER,
  DISTANCE_UNITS,
  VOLUME_UNITS,
  CONSUMPTION_UNITS,
} from '@sdflc/utils';

VALUE_TYPES

Numeric codes for data types used with convertStringToValue.

Key	Value
NUMBER	100
INTEGER	101
FLOAT	102
DECIMAL	103
CURRENCY	200
BOOLEAN	300
STRING	400
JSON	500
EMAIL	1001
PHONE	1002
URL	1003

STATUSES

Standard record status codes.

Key	Value
TEST	50
ACTIVE	100
DRAFT	200
PENDING	300
BLOCKED	1000
DISABLED	5000
REMOVED	10000

ACCESS_RIGHTS

Bitmask values for permission checks.

// Combine with bitwise OR
const rights = ACCESS_RIGHTS.LIST | ACCESS_RIGHTS.GET; // => 3

Key	Value
LIST	1
GET	2
CREATE	4
UPDATE	8
REMOVE	16
RUN	32

DISTANCE_UNITS / VOLUME_UNITS / CONSUMPTION_UNITS

Type-safe string constants for unit conversion functions. Always prefer these over raw strings.

DISTANCE_UNITS.KM; // => 'km'
DISTANCE_UNITS.MILES; // => 'mi'

VOLUME_UNITS.LITERS; // => 'l'
VOLUME_UNITS.GALLONS_US; // => 'gal-us'
VOLUME_UNITS.GALLONS_UK; // => 'gal-uk'
VOLUME_UNITS.KWH; // => 'kwh'
VOLUME_UNITS.KG; // => 'kg'

CONSUMPTION_UNITS.L_PER_100KM; // => 'l100km'
CONSUMPTION_UNITS.MPG_US; // => 'mpg-us'
CONSUMPTION_UNITS.KWH_PER_100KM; // => 'kwh100km'
// ... and more

Other constants

import { UUID_EMPTY, UUID_ZERO, ALPHABET, ALPHABET_CODE, EARTH_RADIUS_M } from '@sdflc/utils';

---

Converters

import {
  convertStringToValue,
  stringifyObject,
  parseObject,
  toRadians,
  metersToKm,
  mpsToKmh,
  isElectricUnit,
  isHydrogenUnit,
  isLiquidUnit,
  toMetricDistance,
  fromMetricDistance,
  fromMetricDistanceRounded,
  toMetricVolume,
  fromMetricVolume,
  getConsumptionUnitForFuelType,
  deriveConsumptionUnit,
  calculateConsumption,
} from '@sdflc/utils';

convertStringToValue(value, valueType)

Converts a string to a typed value using a VALUE_TYPES constant.

convertStringToValue('42', VALUE_TYPES.INTEGER); // => 42
convertStringToValue('3.14', VALUE_TYPES.FLOAT); // => 3.14
convertStringToValue('true', VALUE_TYPES.BOOLEAN); // => true

stringifyObject(config, defaultObj?)

Safely JSON-stringifies an object. Returns the stringified defaultObj on failure.

stringifyObject({ a: 1 }); // => '{"a":1}'
stringifyObject(circular, { ok: 1 }); // => '{"ok":1}'

parseObject(jsonString, defaultObj)

Safely parses a JSON string into an object shaped like defaultObj. Fills in missing keys from defaults and ignores type mismatches.

parseObject('{"name":"Alice"}', { name: '', age: 0 });
// => { name: 'Alice', age: 0 }

Unit conversion functions

All return null for null/undefined inputs.

toRadians(180); // => 3.14159...
metersToKm(1500); // => 1.5
mpsToKmh(10); // => 36

toMetricDistance(10, DISTANCE_UNITS.MILES); // => 16.093
fromMetricDistance(16.0934, DISTANCE_UNITS.MILES); // => ~10

toMetricVolume(1, VOLUME_UNITS.GALLONS_US); // => 3.785
fromMetricVolume(3.785, VOLUME_UNITS.GALLONS_US); // => ~1

calculateConsumption(distanceKm, volumeOrEnergy, consumptionUnit)

Calculates fuel/energy consumption in the specified unit. Supports liquid, electric, and hydrogen units.

// 10L over 100km = 10 l/100km
calculateConsumption(100, 10, CONSUMPTION_UNITS.L_PER_100KM); // => 10

// 20kWh over 100km = 20 kWh/100km
calculateConsumption(100, 20, CONSUMPTION_UNITS.KWH_PER_100KM); // => 20

---

Geo

import {
  buildCoordinatesStr,
  extractLatitudeLongitude,
  isValidCoordinate,
  calcDistance,
  areCoordinatesNear,
  findNearestLocation,
  haversineDistanceM,
  formatCoordinates,
  createBoundingBox,
  isWithinBoundingBox,
  calculateBearing,
  bearingDelta,
  calculateTotalDistance,
} from '@sdflc/utils';

buildCoordinatesStr(coords, precision?)

Formats a GeoCoords object as "lat, lng" string. Defaults to 5 decimal places.

buildCoordinatesStr({ latitude: 51.5074, longitude: -0.1278 });
// => '51.50740, -0.12780'

extractLatitudeLongitude(coordinatesStr)

Parses a "lat,lng" string into a GeoCoords object with numeric values.

extractLatitudeLongitude('51.5074,-0.1278');
// => { latitude: 51.5074, longitude: -0.1278 }

isValidCoordinate(coords)

Returns true if the coordinates are non-null, numeric, and within valid lat/lng ranges.

isValidCoordinate({ latitude: 51.5074, longitude: -0.1278 }); // => true
isValidCoordinate({ latitude: 999, longitude: 0 }); // => false

calcDistance(args)

Calculates the great-circle distance between two coordinates using the Haversine formula (atan2 variant). Returns distance in kilometers.

calcDistance({
  position1: { latitude: 51.5074, longitude: -0.1278 },
  position2: { latitude: 48.8566, longitude: 2.3522 },
}); // => ~343 km

haversineDistanceM(coord1, coord2)

Same as calcDistance but returns distance in meters.

haversineDistanceM({ latitude: 51.5074, longitude: -0.1278 }, { latitude: 48.8566, longitude: 2.3522 }); // => ~343000 meters

areCoordinatesNear(coord1, coord2, thresholdM?)

Returns true if two coordinates are within thresholdM meters of each other. Default threshold is DEFAULT_DISTANCE_THRESHOLD_M.

areCoordinatesNear(coordA, coordB, 100); // within 100m?

findNearestLocation(target, locations, getCoords)

Finds the nearest item in locations to target. Returns { item, distance } or null.

const nearest = findNearestLocation(userCoords, stores, (store) => store.coords);
// => { item: nearestStore, distance: 250.5 }

createBoundingBox(center, radiusM)

Creates a BoundingBox around a coordinate with the given radius in meters.

createBoundingBox({ latitude: 51.5074, longitude: -0.1278 }, 1000);
// => { north: ..., south: ..., east: ..., west: ... }

isWithinBoundingBox(coords, box)

Returns true if coords falls within the bounding box.

calculateBearing(p1, p2)

Returns the initial bearing from p1 to p2 in degrees (0–360). Returns null for invalid input.

calculateBearing({ latitude: 0, longitude: 0 }, { latitude: 0, longitude: 10 });
// => ~90 (due East)

bearingDelta(bearing1, bearing2)

Returns the absolute angular difference between two bearings (0–180), handling the 0°/360° wraparound.

bearingDelta(10, 350); // => 20

calculateTotalDistance(points)

Sums great-circle distances between consecutive points. Returns total in meters.

calculateTotalDistance([london, paris, berlin]); // => total meters

---

Languages

import { extractLanguages } from '@sdflc/utils';

extractLanguages(str)

Parses an Accept-Language HTTP header into an ordered array of language tags.

extractLanguages('en-US,en;q=0.9,ru;q=0.8,fr;q=0.7');
// => ['en-US', 'en', 'ru', 'fr']

---

Logger

import { Logger } from '@sdflc/utils';
import { LoggerLevels } from '@sdflc/utils/interfaces';

A configurable logger with level filtering, optional timestamp, request ID, and module name prefixes.

Levels (lowest to highest)

NONE → ERROR → WARNING → LOG → DEBUG

Only messages at or below the current level are emitted.

Basic usage

const logger = new Logger({ level: LoggerLevels.DEBUG });

logger.debug('Fetching user...');
logger.log('User fetched');
logger.warn('Cache miss');
logger.error('Connection failed');

Custom handlers

const logger = new Logger({
  level: LoggerLevels.LOG,
  log: (msg) => myLoggingService.info(msg),
  error: (msg) => myLoggingService.error(msg),
});

Prefix options

const logger = new Logger({
  level: LoggerLevels.DEBUG,
  timestamp: true, // prepend timestamp to every line
  timestampUtc: true, // use UTC (default: local time)
  requestId: 'req-abc123',
  module: 'UserService',
});

logger.log('User created');
// => [20250325-143022.123Z] [req-abc123] [UserService] User created

setLevel(newLevel) / getLevel()

logger.setLevel(LoggerLevels.ERROR); // suppress everything below ERROR
logger.getLevel(); // => LoggerLevels.ERROR

---

MeasureTool

import { MeasureTool } from '@sdflc/utils';

A cross-environment performance measurement utility using performance.now() (available in Node.js 16+ and all modern browsers).

Basic measurement

const tool = new MeasureTool();
tool.start();

// ... do work ...
const result = tool.stop('total');
console.log(result.durationMs); // milliseconds

Checkpoints

tool.start();
await fetchData();
tool.addCheckpoint('fetch');

await processData();
tool.addCheckpoint('process');

const final = tool.stop('done');
console.log(tool.getCheckpoints());
// => [{ name: 'fetch', durationMs: 120, hrtime: [...] }, ...]

measureExecTime(name, fn)

Wraps an async function and returns its result along with timing data.

const { result, durationMs } = await tool.measureExecTime('myQuery', async () => {
  return await db.query('SELECT ...');
});

threadBlockTime(name?, fn?)

Measures event-loop blocking time using setImmediate. Node.js only.

tool.threadBlockTime('check', ({ name, durationMs }) => {
  console.log(`${name} blocked for ${durationMs}ms`);
});

---

Numbers

import { roundNumberValue, roundNumberValues, parseNumericInput } from '@sdflc/utils';

roundNumberValue(value, decimals?)

Rounds a number to decimals decimal places (default: 2).

roundNumberValue(2.34567); // => 2.35
roundNumberValue(2.34567, 3); // => 2.346
roundNumberValue(2.5, 0); // => 3

roundNumberValues(obj, decimals?)

Recursively rounds all numeric values in an object or array in place. Also returns the mutated value.

const data = { price: 9.9999, tax: 1.2345, label: 'item' };
roundNumberValues(data);
// data => { price: 10, tax: 1.23, label: 'item' }

roundNumberValues([1.111, 2.999]); // => [1.11, 3]

parseNumericInput(value)

Normalises a value from a numeric input field into number | null.

parseNumericInput('42'); // => 42
parseNumericInput(''); // => null
parseNumericInput(null); // => null
parseNumericInput('abc'); // => null
parseNumericInput(NaN); // => null

---

Objects

import { setNullOnEmptyString, onlyPropsOf, compactObject, cloneDeep } from '@sdflc/utils';

setNullOnEmptyString(obj)

Recursively replaces all empty string values ('') with null in an object or array.

setNullOnEmptyString({ firstName: 'John', lastName: '' });
// => { firstName: 'John', lastName: null }

setNullOnEmptyString({ user: { name: '', age: 30 } });
// => { user: { name: null, age: 30 } }

setNullOnEmptyString([{ a: '' }, { a: 'keep' }]);
// => [{ a: null }, { a: 'keep' }]

onlyPropsOf(source, destinationType)

Creates an instance of destinationType and copies only the properties that exist on that class from source.

class UserDto {
  id = 0;
  name = '';
}

onlyPropsOf({ id: 1, name: 'Alice', extra: 'ignored' }, UserDto);
// => UserDto { id: 1, name: 'Alice' }

compactObject(obj)

Recursively removes all undefined properties from an object or array. null values are preserved.

compactObject({ a: 1, b: undefined, c: { d: undefined, e: 2 } });
// => { a: 1, c: { e: 2 } }

cloneDeep(obj)

Creates a deep clone handling Date, undefined, NaN, Infinity, and circular references correctly.

const original = { a: { b: 1 }, d: new Date() };
const clone = cloneDeep(original);
clone.a.b = 99;
original.a.b; // => 1 (unchanged)
clone.d instanceof Date; // => true

---

Strings

import { camelKeys, camelResponse, pascalCase, pascalCases, buildKey, buildKeys, isIdEmpty, slug } from '@sdflc/utils';

camelKeys(result)

Recursively converts all object keys to camelCase. Handles arrays and nested objects. Leaves Date instances and primitives untouched.

camelKeys({ first_name: 'John', last_name: 'Doe' });
// => { firstName: 'John', lastName: 'Doe' }

camelKeys([{ user_id: 1 }, { user_id: 2 }]);
// => [{ userId: 1 }, { userId: 2 }]

camelResponse(result)

Converts object keys to camelCase. Returns the value unchanged if it is falsy or has a rows property (raw database result sets).

camelResponse({ user_id: 1 }); // => { userId: 1 }
camelResponse(null); // => null

pascalCase(name)

Converts a string to PascalCase.

pascalCase('hello_world'); // => 'HelloWorld'
pascalCase('hello-world'); // => 'HelloWorld'

pascalCases(args)

Recursively converts all keys in an object or array to PascalCase. Supports a mapKey override for specific keys.

pascalCases({ src: { first_name: 'Alice' } });
// => { FirstName: 'Alice' }

pascalCases({ src: { id: 1, name: 'Alice' }, mapKey: { id: 'Id' } });
// => { Id: 1, Name: 'Alice' }

buildKey(keys)

Converts a string, number, array, or object to a slug-based key string.

buildKey('hello world'); // => 'hello-world'
buildKey(42); // => '42'
buildKey(['foo', 'bar']); // => 'foo-bar'
buildKey({ a: 1 }); // => '{"a":1}'

buildKeys(keys)

Calls buildKey on each item in an array.

buildKeys(['hello world', 42]); // => ['hello-world', '42']

isIdEmpty(value)

Returns true if the value represents an empty/unset ID.

isIdEmpty(null); // => true
isIdEmpty(''); // => true
isIdEmpty('0'); // => true
isIdEmpty(0); // => true
isIdEmpty(UUID_EMPTY); // => true
isIdEmpty('abc-123'); // => false

slug(str)

Converts a string to a URL-friendly slug. Normalises Unicode/accented characters to ASCII equivalents.

slug('Hello World!'); // => 'hello-world'
slug('café résumé'); // => 'cafe-resume'
slug('Привет мир'); // => 'privet-mir'

---

String Helpers

import {
  doesValueMatchAlphabet,
  isLengthBetween,
  areStringsEqual,
  replaceAt,
  insertAt,
  randomString,
  escapeRegExp,
  formatString,
  normalizeName,
} from '@sdflc/utils';

doesValueMatchAlphabet(value, alphabet)

Returns true if every character in value is present in alphabet.

doesValueMatchAlphabet('ABC123', 'ABCDEFGHJKLMNPQRSTUVWXYZ0123456789'); // => true
doesValueMatchAlphabet('abc', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'); // => false

isLengthBetween(str, minLen, maxLen)

Returns true if str length is between minLen and maxLen (inclusive).

isLengthBetween('hello', 3, 10); // => true
isLengthBetween('hi', 3, 10); // => false

areStringsEqual(strLeft, strRight)

Returns true if the two strings are equal ignoring case.

areStringsEqual('Hello', 'hello'); // => true

replaceAt(str, index, replacement)

Replaces characters in str starting at index with replacement.

replaceAt('hello world', 6, 'there'); // => 'hello there'

insertAt(str, index, insert)

Inserts insert into str at index without removing any characters.

insertAt('helo', 3, 'l'); // => 'hello'

randomString(length, alphabet?)

Generates a random string. Not suitable for cryptographic purposes.

randomString(8); // => 'A3KF9Z2M'  (from default alphabet)
randomString(6, 'abc'); // => 'bcaabc'

escapeRegExp(str)

Escapes all regex special characters so the string can be safely used in new RegExp(...).

escapeRegExp('{{name}}'); // => '\\{\\{name\\}\\}'

formatString(str, obj, opt?)

Replaces {{key}} placeholders in a template string with values from obj. Delimiters are configurable. Null/undefined values leave the placeholder unchanged.

formatString('Hello {{name}}!', { name: 'Alice' });
// => 'Hello Alice!'

formatString('Hi ${name}!', { name: 'Bob' }, { leftWrapper: '${', rightWrapper: '}' });
// => 'Hi Bob!'

normalizeName(name)

Trims and lowercases a name string. Returns undefined for null/undefined input.

normalizeName('  Alice  '); // => 'alice'
normalizeName(null); // => undefined

---

StrOrderHelpers

import { StrOrderHelpers } from '@sdflc/utils';

A counter that operates in any numeric base (default: base-36) using string representations. Useful for generating sortable string order keys.

const order = new StrOrderHelpers({ start: '100', step: '5' });

order.current(); // => '100'
order.increase(); // => '105'
order.increase(); // => '10a'
order.decrease(); // => '105'
order.reset(); // => resets to '100'

Arithmetic helpers

order.add('1000', 'bb'); // => '10bb'
order.subtract('10cc', 'cc'); // => '1000'
order.addValue('aa'); // adds to current counter, returns new value
order.subtractValue('a'); // subtracts from current counter

valueBetween(valueA, valueB)

Finds the midpoint between two values in the current base. Returns null if no distinct midpoint exists (adjacent or equal values).

order.valueBetween('aaa', 'ccc'); // => 'bbb'
order.valueBetween('100', '104'); // => '102'
order.valueBetween('100', '101'); // => null

Constructor options

Option	Type	Default	Description
start	string	'0'	Initial counter value
step	string	'1'	Increment/decrement step
base	number	36	Numeric base (2–36)

---

Transformers

import { buildHierarchy, mapArrayBy, flattenHierarchy, getLowestLevelItems } from '@sdflc/utils';

buildHierarchy(arr, idField, parentIdField, nameForChildren)

Converts a flat array into a tree structure. Items with no valid parent are roots; items whose parent isn't in the array are orphans.

const flat = [
  { id: '1', parentId: null, name: 'Root' },
  { id: '2', parentId: '1', name: 'Child' },
];

buildHierarchy(flat, 'id', 'parentId', 'children');
// => {
//   tree: [{ id: '1', name: 'Root', children: [{ id: '2', name: 'Child', children: [] }] }],
//   orphans: []
// }

mapArrayBy(arr, mapBy, opt?)

Maps an array of objects into a lookup object keyed by one or more fields.

const arr = [
  { id: '1', val: 'a' },
  { id: '2', val: 'b' },
];

mapArrayBy(arr, 'id');
// => { '1': { id: '1', val: 'a' }, '2': { id: '2', val: 'b' } }

mapArrayBy(arr, 'id', { multiple: true });
// => { '1': [{ id: '1', val: 'a' }], '2': [{ id: '2', val: 'b' }] }

mapArrayBy(arr, ['id', 'val']);
// => { id: { '1': {...}, '2': {...} }, val: { a: {...}, b: {...} } }

flattenHierarchy(arr, nameForChildren, opt?)

Flattens a tree into a depth-first ordered array.

flattenHierarchy(tree, 'children');
// => [root, child1, grandchild1, child2, ...]

// With callback:
flattenHierarchy(tree, 'children', {
  onItem: (item) => console.log(item.name),
});

getLowestLevelItems(arr, idField, parentIdField, nameForChildren, setRoot?)

Returns only the leaf nodes from a flat array. Optionally attaches a rootId to each leaf.

getLowestLevelItems(flat, 'id', 'parentId', 'children', true);
// => [
//   { id: '4', ..., rootId: '1' },
//   { id: '5', ..., rootId: '1' },
// ]

---

URL Params

import { buildURLSearchParams } from '@sdflc/utils';

buildURLSearchParams(data)

Converts a plain object into a URLSearchParams instance. Supports nested objects (dot notation), arrays (bracket notation), Date values, and mixed structures. Null and undefined values are omitted.

buildURLSearchParams({ name: 'Alice', age: 30 }).toString();
// => 'name=Alice&age=30'

buildURLSearchParams({ tags: ['a', 'b'] }).toString();
// => 'tags[0]=a&tags[1]=b'

buildURLSearchParams({ address: { city: 'Calgary' } }).toString();
// => 'address.city=Calgary'

buildURLSearchParams({
  filters: [{ field: 'status', values: ['active', 'pending'] }],
}).toString();
// => 'filters[0].field=status&filters[0].values[0]=active&filters[0].values[1]=pending'

buildURLSearchParams({ createdAt: new Date('2025-01-01T00:00:00Z') }).toString();
// => 'createdAt=2025-01-01T00:00:00.000Z'

---

License

MIT