@codeleap/utils 6.3.0 → 6.8.0

package/src/array.ts

@@ -2,19 +2,26 @@ import { FunctionType } from '@codeleap/types'
 
 type GetterFunction<T> = FunctionType<[T, number], string | number> | keyof T
 
+/**
+ * Indexes an array into an object keyed by a derived value.
+ *
+ * `keyAccessor` may be a property name string or a callback that returns a
+ * key. When omitted, array indices are used as keys. Duplicate keys silently
+ * overwrite earlier entries.
+ */
 export function objectFromArray<T, Getter extends GetterFunction<T>>(
   arr: T[],
   keyAccessor?: Getter,
 ): Record<string, T> {
-  let getObjectKey = (_, idx) => idx
+  let getObjectKey: (value: T, idx: number) => string | number = (_, idx) => idx
 
   if (keyAccessor) {
     switch (typeof keyAccessor) {
       case 'string':
-        getObjectKey = (value) => value[keyAccessor]
+        getObjectKey = (value: T) => value[keyAccessor as keyof T] as unknown as string | number
         break
       case 'function':
-        getObjectKey = keyAccessor
+        getObjectKey = keyAccessor as (value: T, idx: number) => string | number
         break
     }
   }
@@ -24,6 +31,13 @@ export function objectFromArray<T, Getter extends GetterFunction<T>>(
   return Object.fromEntries(indexedMap)
 }
 
+/**
+ * Returns a deduplicated copy of `array` where uniqueness is determined by
+ * the value returned from `getProperty`.
+ *
+ * When duplicates exist, the **last** occurrence wins because `objectFromArray`
+ * overwrites earlier entries with the same key.
+ */
 export function uniqueArrayByProperty<T, G extends GetterFunction<T>>(
   array: T[],
   getProperty: G,
@@ -31,6 +45,12 @@ export function uniqueArrayByProperty<T, G extends GetterFunction<T>>(
   return Object.values(objectFromArray(array, getProperty))
 }
 
+/**
+ * Recursively flattens a nested array of arbitrary depth into a single-level array.
+ *
+ * Unlike `Array.prototype.flat(Infinity)`, this implementation does not rely on
+ * native flat support and works identically across all environments.
+ */
 export function flatten<T extends unknown>(arr: T[]) {
   let newArr = [] as T[]
 
@@ -45,6 +65,11 @@ export function flatten<T extends unknown>(arr: T[]) {
   return newArr
 }
 
+/**
+ * Returns an inclusive integer array from `start` to `end`.
+ *
+ * Both bounds are included: `range(1, 3)` → `[1, 2, 3]`.
+ */
 export function range(start: number, end: number) {
   const length = end - start + 1
   return Array.from({ length }, (_, index) => index + start)

package/src/cloneDeep.ts

@@ -1,14 +1,22 @@
-export function cloneDeep(value) {
+/**
+ * Produces a full recursive clone of `value` without any external dependencies.
+ *
+ * Supported types: primitives (returned as-is), plain objects, arrays, `Date`,
+ * `Map`, `Set`, and `RegExp`. Class instances with prototype methods beyond
+ * these built-ins are cloned as plain objects — prototype chain is not preserved.
+ * Circular references will cause a stack overflow.
+ */
+export function cloneDeep<T = any>(value: T): T {
   if (value === null || typeof value !== 'object') {
     return value
   }
 
   if (Array.isArray(value)) {
-    return value.map(cloneDeep)
+    return value.map(cloneDeep) as unknown as T
   }
 
   if (value instanceof Date) {
-    return new Date(value.getTime())
+    return new Date(value.getTime()) as unknown as T
   }
 
   if (value instanceof Map) {
@@ -16,7 +24,7 @@ export function cloneDeep(value) {
     value.forEach((v, k) => {
       clonedMap.set(k, cloneDeep(v))
     })
-    return clonedMap
+    return clonedMap as unknown as T
   }
 
   if (value instanceof Set) {
@@ -24,20 +32,20 @@ export function cloneDeep(value) {
     value.forEach((v) => {
       clonedSet.add(cloneDeep(v))
     })
-    return clonedSet
+    return clonedSet as unknown as T
   }
 
   if (value instanceof RegExp) {
-    return new RegExp(value.source, value.flags)
+    return new RegExp(value.source, value.flags) as unknown as T
   }
 
-  const clonedObj = {}
+  const clonedObj: Record<string, unknown> = {}
 
   for (const key in value) {
     if (Object.prototype.hasOwnProperty.call(value, key)) {
-      clonedObj[key] = cloneDeep(value[key])
+      clonedObj[key] = cloneDeep((value as Record<string, unknown>)[key])
     }
   }
 
-  return clonedObj
+  return clonedObj as unknown as T
 }

package/src/colors.ts

@@ -1,7 +1,13 @@
 import tinycolor from 'tinycolor2'
 import { TypeGuards } from '@codeleap/types'
 
-export function hexToRgb(hex) {
+/**
+ * Parses a 6-digit hex colour string (with or without leading `#`) into its
+ * `{ r, g, b }` components.
+ *
+ * Returns `null` for invalid or short (3-digit) hex values.
+ */
+export function hexToRgb(hex: string) {
   const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex)
   return result
     ? {
@@ -12,8 +18,18 @@ export function hexToRgb(hex) {
     : null
 }
 
-const shadeColorCache = {}
-export function shadeColor(color: string, percent = 0, opacity = null) {
+const shadeColorCache: Record<string, string> = {}
+
+/**
+ * Lightens or darkens `color` by `percent` and optionally applies `opacity`,
+ * returning an `rgba(...)` string.
+ *
+ * - Positive `percent` → lighten; negative → darken (magnitude is used).
+ * - `opacity` must be in the `0–1` range (passed directly to tinycolor's `setAlpha`).
+ * - Results are memoised in a module-level cache keyed by the serialised parameters,
+ *   so repeated calls with identical arguments are effectively free.
+ */
+export function shadeColor(color: string, percent = 0, opacity: number | null = null) {
   const _color = color.trim()
   const serialParams = [_color, percent.toString()]
   if (TypeGuards.isNumber(opacity)) {

package/src/date.ts

@@ -14,6 +14,15 @@ const removeTimezoneAndFormat = (date: any, format = 'YYYY-MM-DD') => {
   return dayjs(normalizedDate).startOf('day').format(format)
 }
 
+/**
+ * Date helpers that normalise timezone-sensitive values before formatting.
+ *
+ * - `removeTimezoneAndFormat(date, format?)` — strips the time component from
+ *   a `Date` or ISO string, anchors it to noon local time, then formats with
+ *   dayjs. This prevents off-by-one-day errors that occur when UTC midnight
+ *   falls on a different calendar day in the user's timezone. Returns `''` for
+ *   falsy input.
+ */
 export const dateUtils = {
   removeTimezoneAndFormat,
 }

package/src/faker.ts

@@ -25,6 +25,19 @@ function number(min: number = 0, max: number = 100) {
   return Math.floor(Math.random() * (max - min + 1)) + min
 }
 
+/**
+ * Lightweight in-house fixture-data generator with no external dependencies.
+ *
+ * Provided methods:
+ * - `firstName()` / `lastName()` — random entries from hard-coded name lists.
+ * - `name()` — space-joined first + last name.
+ * - `animal()` — random animal name.
+ * - `number(min?, max?)` — random integer in `[min, max]` (default 0–100).
+ *
+ * All selections use `Math.random`, so results are not reproducible across calls.
+ * Use this instead of heavy faker libraries in tests or seed scripts where the
+ * small vocabulary is sufficient.
+ */
 export const faker = {
   lastName: () => getRandom(surnames),
   firstName: () => getRandom(names),

package/src/file.ts

@@ -1,5 +1,13 @@
 const separators = /[\\\/]+/
 
+/**
+ * Splits a file system path into its directory, base name, and extension.
+ *
+ * Both `/` and `\` are treated as separators, so Windows and POSIX paths are
+ * handled uniformly. Files without an extension return an empty string for
+ * `extension`. The returned `path` is always joined with `/` regardless of the
+ * original separator.
+ */
 export function parseFilePathData(path: string) {
   const parts = path.split(separators)
 

package/src/locale.ts

@@ -1,5 +1,12 @@
 import { AnyRecord } from '@codeleap/types'
 
+/**
+ * Finds the closest matching key in `languageDictionary` for a given `locale`.
+ *
+ * Matching uses only the first two characters (the language subtag), so `'en-AU'`
+ * will match an `'en-US'` dictionary key. Returns `defaultLocale` when no
+ * partial match exists.
+ */
 export function getSimilarLocale(
   locale: string,
   defaultLocale: string,

package/src/misc.ts

@@ -1,6 +1,13 @@
 import { capitalize } from './string'
 import { StylesOf } from '@codeleap/types'
 
+/**
+ * Converts a remote image URL into a file-upload-compatible object
+ * (`{ uri, name, type }`).
+ *
+ * The `type` is inferred from the URL's file extension. Returns `null` when
+ * `imagePath` is falsy, making it safe to pass directly to optional file-input APIs.
+ */
 export function imagePathToFileObject(imagePath: string | null) {
   const parts = imagePath ? imagePath.split('.') : ''
 
@@ -17,7 +24,7 @@ export function imagePathToFileObject(imagePath: string | null) {
   return fileValue
 }
 
-const letterToColorMap = {
+const letterToColorMap: Record<string, string> = {
   a: '#7CB9E8',
   b: '#3a9e77',
   c: '#A3C1AD',
@@ -46,12 +53,20 @@ const letterToColorMap = {
   z: '#ff8295',
 }
 
+/**
+ * Maps the first character of `anyString` to a deterministic colour for use in
+ * avatar placeholders.
+ *
+ * Lookup is case-insensitive. Returns `'#999999'` for empty, undefined, or
+ * characters not in the `a–z` range.
+ */
 export function matchInitialToColor(anyString?: string) {
   if (!anyString) return '#999999'
   return letterToColorMap[anyString.toLowerCase().charAt(0)] || '#999999'
 }
 
-export function waitFor(ms) {
+/** Returns a Promise that resolves after `ms` milliseconds. */
+export function waitFor(ms: number) {
   return new Promise<void>((resolve) => {
     setTimeout(() => {
       resolve()
@@ -64,15 +79,23 @@ type ParseSourceUrlArg = {
   src?: string
 }
 
+/**
+ * Resolves a media URL from either a raw string or a `{ source?, src? }` object.
+ *
+ * - Paths starting with `/media/` are prefixed with `Settings.BaseURL`.
+ * - Absolute URLs are returned unchanged.
+ * - Empty/missing addresses fall back to a random `picsum.photos` placeholder.
+ * - Returns `null` for a falsy `args` argument.
+ */
 export function parseSourceUrl(args: string, Settings?: any): string
 export function parseSourceUrl(
   args: ParseSourceUrlArg,
   Settings?: any
-): string
+): string | null
 export function parseSourceUrl(
   args: ParseSourceUrlArg | string,
   Settings?: any,
-): string {
+): string | null {
   if (!args) return null
 
   let res = ''
@@ -94,8 +117,16 @@ export function parseSourceUrl(
   return res
 }
 
+/**
+ * Extracts style entries from a variant styles map whose keys begin with `match`,
+ * returning them as a new object with the prefix stripped and the first
+ * remaining character lowercased.
+ *
+ * Used internally by component style systems to pull out sub-part styles
+ * (e.g. `inputLabel`, `inputWrapper`) into their own namespaced objects.
+ */
 export function getNestedStylesByKey<T extends StylesOf<any>>(match:string, variantStyles: T) {
-  const styles = {}
+  const styles: Record<string, unknown> = {}
 
   for (const [key, value] of Object.entries(variantStyles)) {
 
@@ -108,6 +139,15 @@ export function getNestedStylesByKey<T extends StylesOf<any>>(match:string, vari
   return styles
 }
 
+/**
+ * Heuristically detects whether the app has been React Fast Refreshed since
+ * initial launch.
+ *
+ * Compares the elapsed time since `Settings.Environment.InitTime` against a
+ * 1-second threshold. Fast Refresh typically completes well under 1 second from
+ * app start; anything longer suggests a subsequent refresh rather than cold boot.
+ * Returns `undefined` and logs a warning when `InitTime` is not set.
+ */
 export function hasFastRefreshed(Settings: any) {
   if (Settings?.Environment?.InitTime) {
     const timeFromStartup = (new Date()).getTime() - Settings.Environment.InitTime.getTime()
@@ -120,9 +160,17 @@ export function hasFastRefreshed(Settings: any) {
   }
 }
 
-const throttleTimerId = []
-
-export function throttle(func, ref, delay) {
+const throttleTimerId: Record<string | number, ReturnType<typeof setTimeout> | undefined> = {}
+
+/**
+ * Leading-edge throttle keyed by a `ref` identifier rather than by function reference.
+ *
+ * `func` is called immediately on the first invocation for a given `ref`; subsequent
+ * calls with the same `ref` are dropped until `delay` milliseconds have elapsed.
+ * Using a string/number `ref` allows multiple independent throttle timers to coexist
+ * in a single module without needing to hold separate timer handles.
+ */
+export function throttle(func: () => void, ref: string | number, delay: number) {
   if (throttleTimerId[ref]) {
     return
   }

package/src/object.ts

@@ -1,10 +1,16 @@
 import { FunctionType, AppSettings } from '@codeleap/types'
 
-export function deepMerge(base = {}, changes = {}): any {
-  const obj = {
+/**
+ * Recursively merges `changes` into `base`, deep-merging nested plain objects.
+ *
+ * Arrays and `Date` instances are treated as scalar values — they replace rather
+ * than merge. If `changes` is not iterable, it is returned as-is.
+ */
+export function deepMerge(base: Record<string, any> = {}, changes: Record<string, any> = {}): any {
+  const obj: Record<string, any> = {
     ...base,
   }
-  let changeEntries = []
+  let changeEntries: [string, any][] = []
   try {
     changeEntries = Object.entries(changes)
   } catch (e) {
@@ -21,30 +27,46 @@ export function deepMerge(base = {}, changes = {}): any {
   return obj
 }
 
+/**
+ * Like `Array.prototype.map` but over an object's entries.
+ *
+ * Returns an array — not a new object — so it is useful when you need to
+ * transform key-value pairs into arbitrary values (e.g. JSX elements).
+ */
 export function mapObject<T>(
   obj: T,
   callback: FunctionType<[[keyof T, T[keyof T]]], any>,
 ) {
-  return Object.entries(obj).map((args) => callback(args as [keyof T, T[keyof T]]),
+  return Object.entries(obj as Record<string, unknown>).map((args) => callback(args as [keyof T, T[keyof T]]),
   )
 }
 
-export const deepSet = ([path, value]) => {
-  const parts = path.split('.')
-  const newObj = Array.isArray(value) ? [] : {}
-
-  if (parts.length === 1) {
-    newObj[parts[0]] = value
-  } else {
-    newObj[parts[0]] = deepSet([parts.slice(1).join('.'), value])
+/**
+ * Sets a value at an arbitrarily deep dot-separated `path`, mutating `base` in place
+ * and returning it.
+ *
+ * Numeric path segments are coerced to array indices when the current node is an array.
+ */
+export const deepSet = (base: any = {}, path: string, value: any): any => {
+  const keys = path.split('.')
+  const obj = base
+  let thisKey: string | number = keys[0]
+  if (Array.isArray(base)) {
+    thisKey = Number(thisKey)
   }
-
-  return newObj
+  obj[thisKey] = keys.length === 1 ? value : deepSet(obj[thisKey], keys.slice(1).join('.'), value)
+  return obj
 }
 
-export const deepGet = (path, obj) => {
+/**
+ * Reads a value from `obj` at a dot-separated `path`.
+ *
+ * Returns `undefined` (without throwing) when any intermediate node is absent,
+ * because property access on `undefined` propagates silently through the loop.
+ */
+export const deepGet = (path: string, obj: Record<string, any>) => {
   const parts = path.split('.')
-  let newObj = { ...obj }
+  let newObj: Record<string, any> = { ...obj }
 
   for (const prop of parts) {
     newObj = newObj[prop]
@@ -53,8 +75,13 @@ export const deepGet = (path, obj) => {
   return newObj
 }
 
-export function objectPaths(obj) {
-  let paths = []
+/**
+ * Returns every dot-separated leaf path in a nested object.
+ *
+ * Array values are treated as leaves — their indices are not traversed.
+ */
+export function objectPaths(obj: Record<string, any>): string[] {
+  let paths: string[] = []
 
   Object.entries(obj).forEach(([key, value]) => {
     if (!Array.isArray(value) && typeof value === 'object') {
@@ -67,10 +94,17 @@ export function objectPaths(obj) {
   return paths
 }
 
+/** Returns `true` only for `string`, `number`, and `boolean` — `null`, `undefined`, and objects are excluded. */
 export function isValuePrimitive(a:any) {
   return ['string', 'number', 'boolean'].includes(typeof a)
 }
 
+/**
+ * Inline ternary helper for spread-merging optional style or prop objects.
+ *
+ * Intended for use inside object spreads where the ternary would otherwise
+ * require wrapping: `{ ...optionalObject(flag, trueProps, {}) }`.
+ */
 export function optionalObject(condition: boolean, ifTrue: any, ifFalse: any) {
   return condition ? ifTrue : ifFalse
 }
@@ -79,7 +113,16 @@ type TraverseRecArgs = {path:string[]; value: any; depth: number; key: string; t
 
 type TraverseCallback = (args?: TraverseRecArgs) => {stop?: boolean } | void
 
-export function traverse(obj = {}, callback:TraverseCallback, args?: TraverseRecArgs) {
+/**
+ * Depth-first walk over a nested object, invoking `callback` at each node.
+ *
+ * The callback receives metadata about each visited node (`path`, `depth`,
+ * `key`, `type`, `primitive`). Primitive leaves fire the callback once; object
+ * nodes fire it for each child before recursing into it. Returning `{ stop: true }`
+ * from the callback is accepted by the type but **does not halt traversal** —
+ * the implementation does not check the return value.
+ */
+export function traverse(obj: any = {}, callback:TraverseCallback, args?: TraverseRecArgs) {
   const isPrimitive = isValuePrimitive(obj)
 
   const info = {
@@ -127,16 +170,34 @@ export function traverse(obj = {}, callback:TraverseCallback, args?: TraverseRec
   }
 }
 
+/**
+ * Identity helper that returns its argument unchanged, typed as `AppSettings`.
+ *
+ * Exists solely to give TypeScript a typed entry point for authoring settings
+ * objects so that editors provide autocompletion and type errors at the
+ * definition site rather than at the point of use.
+ */
 export function createSettings<T extends AppSettings>(a:T): T {
   return a
 }
 
+/**
+ * Returns `obj.id` if it exists, otherwise `undefined`.
+ *
+ * Intended as a default `keyExtractor` in list utilities where records are
+ * expected to carry an `id` field.
+ */
 export function extractKey(obj:any) {
   if (obj.id) {
     return obj.id
   }
 }
 
+/**
+ * Returns a new object containing only the entries for which `predicate` returns `true`.
+ *
+ * Only own enumerable keys are visited; prototype-chain properties are skipped.
+ */
 export function objectPickBy<K extends string = string, P = any>(obj: Record<K, P>, predicate: (valueKey: P, key: K) => boolean) {
   const result = {} as Record<K, P>
 
@@ -149,8 +210,15 @@ export function objectPickBy<K extends string = string, P = any>(obj: Record<K,
   return result
 }
 
+/**
+ * Rebuilds an object by running every entry through `predicate`, which must
+ * return a `[newKey, newValue]` tuple.
+ *
+ * Keys returned by `predicate` need not be unique — later entries silently
+ * overwrite earlier ones if they resolve to the same key.
+ */
 export function transformObject<K extends string = string, T extends string = string>(obj: Record<K, T>, predicate: (value: T, key: K) => [K, T]): Record<string, any> {
-  const result = {}
+  const result: Record<string, any> = {}
 
   for (const key in obj) {
     const [newKey, newValue] = predicate?.(obj?.[key], key)
@@ -160,3 +228,37 @@ export function transformObject<K extends string = string, T extends string = st
 
   return result
 }
+type LowercaseFirst<S extends string> = S extends `${infer F}${infer Rest}` ? `${Lowercase<F>}${Rest}` : S
+
+/**
+ * Mapped type that extracts keys of `T` starting with `P`, strips the prefix,
+ * and lowercases the first character of the remainder.
+ *
+ * Used to derive the return type of {@link filterObjectByPrefix} at compile time.
+ * For example, `FilterByPrefix<{ onPress: () => void }, 'on'>` yields `{ press: () => void }`.
+ */
+export type FilterByPrefix<T, P extends string> = {
+  [K in Extract<keyof T, `${P}${string}`> as K extends `${P}${infer Rest}` ? LowercaseFirst<Rest> : never]: T[K]
+}
+
+/**
+ * Returns a new object containing only keys that start with `prefix`, with the
+ * prefix stripped and the first remaining character lowercased.
+ *
+ * Useful for splitting a flat props object into logical groups, e.g. separating
+ * all `inputXxx` props from a combined component interface.
+ */
+export function filterObjectByPrefix<T extends Record<string, any>, P extends string>(
+  obj: T,
+  prefix: P,
+): FilterByPrefix<T, P> {
+  const result = {} as any
+  for (const key in obj) {
+    if (key.startsWith(prefix)) {
+      const newKey = key.slice(prefix.length)
+      const formattedKey = newKey.charAt(0).toLowerCase() + newKey.slice(1)
+      result[formattedKey] = obj[key]
+    }
+  }
+  return result
+}