@kdtlabs/utils 0.0.4 → 0.0.6

package/src/numbers/conversions.ts

@@ -0,0 +1,83 @@
+import type { Numberish } from './types'
+import { SUBSCRIPT_CHARS } from './constants'
+import { roundTo } from './maths'
+
+export function toSubscriptDigits(input: Numberish) {
+    let result = ''
+
+    for (const char of input.toString()) {
+        result += SUBSCRIPT_CHARS[char] ?? char
+    }
+
+    return result
+}
+
+export function parseExponential(input: Numberish) {
+    const str = input.toString().toLowerCase()
+    const [mantissa, rawExp] = str.split('e')
+
+    if (rawExp === undefined) {
+        return str
+    }
+
+    const [rawInt, fracPart = ''] = mantissa?.split('.') ?? []
+
+    if (!rawInt) {
+        return str
+    }
+
+    const sign = rawInt.startsWith('-') ? '-' : ''
+    const intPart = sign ? rawInt.slice(1) : rawInt
+    const exp = Number(rawExp)
+
+    if (exp >= 0) {
+        const neededZeros = Math.max(0, exp - fracPart.length)
+        const padded = fracPart + '0'.repeat(neededZeros)
+
+        if (padded.length > exp) {
+            return `${sign}${intPart}${padded.slice(0, exp)}.${padded.slice(exp)}`
+        }
+
+        return `${sign}${intPart}${padded}`
+    }
+
+    const absExp = -exp
+    const digits = intPart + fracPart
+    const totalLeadingZeros = Math.max(0, absExp - intPart.length)
+
+    return `${sign}0.${'0'.repeat(totalLeadingZeros)}${digits}`
+}
+
+export function toOrdinal(n: number) {
+    const remainder100 = Math.abs(n) % 100
+    const remainder10 = remainder100 % 10
+
+    if (remainder100 >= 11 && remainder100 <= 13) {
+        return `${n}th`
+    }
+
+    switch (remainder10) {
+        case 1:
+            return `${n}st`
+        case 2:
+            return `${n}nd`
+        case 3:
+            return `${n}rd`
+        default:
+            return `${n}th`
+    }
+}
+
+export function toPercent(value: number, total: number, decimals?: number) {
+    if (total === 0) {
+        return 0
+    }
+
+    const result = (value / total) * 100
+
+    if (decimals === undefined) {
+        return result
+    }
+
+    return roundTo(result, decimals)
+}

package/src/numbers/factories.ts

@@ -0,0 +1,6 @@
+export function random(min: number, max: number) {
+    const lo = Math.min(min, max)
+    const hi = Math.max(min, max)
+
+    return Math.floor(Math.random() * (hi - lo + 1)) + lo
+}

package/src/numbers/formats.ts

@@ -0,0 +1,52 @@
+import type { Numberish } from './types'
+import { parseExponential, toSubscriptDigits } from './conversions'
+
+export function countLeadingZeros(input: string) {
+    let count = 0
+
+    for (let i = 0; i < input.length && input[i] === '0'; i++) {
+        count++
+    }
+
+    return count
+}
+
+export interface FormatNumberOptions extends Intl.NumberFormatOptions {
+    formatLeadingZeros?: (count: number) => string
+    groupFractionLeadingZeros?: boolean
+    locales?: Intl.LocalesArgument
+}
+
+export function formatNumber(input: Numberish, options_: FormatNumberOptions = {}) {
+    const { formatLeadingZeros = (count: number) => `0${toSubscriptDigits(count)}`, groupFractionLeadingZeros = true, locales = 'en-US', maximumFractionDigits = 4, ...options } = options_
+
+    const formatInput = (digits: number) => (
+        new Intl.NumberFormat(locales, { ...options, maximumFractionDigits: digits }).format(input as Intl.StringNumericLiteral)
+    )
+
+    if (!groupFractionLeadingZeros) {
+        return formatInput(maximumFractionDigits)
+    }
+
+    const numericStr = parseExponential(input)
+    const [, fractionPart = ''] = numericStr.split('.', 2)
+    const leadingZerosCount = countLeadingZeros(fractionPart)
+
+    if (leadingZerosCount <= 1) {
+        return formatInput(maximumFractionDigits)
+    }
+
+    const replaceFractionZeros = (part: Intl.NumberFormatPart) => {
+        if (part.type === 'fraction') {
+            return `${formatLeadingZeros(leadingZerosCount)}${part.value.slice(leadingZerosCount)}`
+        }
+
+        return part.value
+    }
+
+    const parts = new Intl.NumberFormat(locales, {
+        ...options, maximumFractionDigits: maximumFractionDigits + leadingZerosCount,
+    })
+
+    return parts.formatToParts(input as Intl.StringNumericLiteral).map(replaceFractionZeros).join('')
+}

package/src/numbers/guards.ts

@@ -0,0 +1,22 @@
+import type { Numberish, NumberString, Percentage } from './types'
+import { isBigInt, isNumber, isString } from '../core'
+import { SPECIAL_NUMBER_STRINGS } from './constants'
+
+// eslint-disable-next-line security/detect-unsafe-regex -- anchored regex with no backtracking risk on bounded input
+const NUMERIC_PATTERN = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/iu
+
+export const isSpecialNumberString = (value: string) => SPECIAL_NUMBER_STRINGS.has(value)
+
+export function isNumberString<TStrict extends boolean = true>(value: string): value is NumberString<TStrict> {
+    if (isSpecialNumberString(value)) {
+        return true
+    }
+
+    return NUMERIC_PATTERN.test(value)
+}
+
+export const isNumberish = <TStrict extends boolean = true>(input: unknown): input is Numberish<TStrict> => (
+    isNumber(input) || isBigInt(input) || (isString(input) && isNumberString(input))
+)
+
+export const isPercentage = (value: number): value is Percentage => value >= 0 && value <= 100

package/src/numbers/index.ts

@@ -0,0 +1,10 @@
+export * from './bigint-math'
+export * from './constants'
+export * from './conversions'
+export * from './factories'
+export * from './formats'
+export * from './guards'
+export * from './maths'
+export * from './ranges'
+
+export type * from './types'

package/src/numbers/maths.ts

@@ -0,0 +1,28 @@
+import { transform } from '../functions'
+
+export const sum = (array: number[]) => array.reduce((a, b) => a + b, 0)
+
+export const avg = (array: number[]) => (array.length === 0 ? 0 : sum(array) / array.length)
+
+export const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max)
+
+export const roundTo = (value: number, decimals: number) => (
+    transform(10 ** decimals, (factor) => Math.round(value * factor) / factor)
+)
+
+export const lerp = (start: number, end: number, t: number) => start + (end - start) * t
+
+export function median(array: number[]) {
+    if (array.length === 0) {
+        return 0
+    }
+
+    const sorted = [...array].toSorted((a, b) => a - b)
+    const mid = Math.floor(sorted.length / 2)
+
+    if (sorted.length % 2 === 0) {
+        return (sorted[mid - 1]! + sorted[mid]!) / 2
+    }
+
+    return sorted[mid]!
+}

package/src/numbers/ranges.ts

@@ -0,0 +1,17 @@
+import { notNullish } from '../core'
+
+export function isValidRange<T extends bigint | number>(start: T, end: T, inclusive = true, min?: T, max?: T) {
+    if (notNullish(min) && start < min) {
+        return false
+    }
+
+    if (notNullish(max) && end > max) {
+        return false
+    }
+
+    return inclusive ? start <= end : start < end
+}
+
+export const isInRange = <T extends bigint | number>(value: T, min: T, max: T, inclusive = true) => (
+    inclusive ? value >= min && value <= max : value > min && value < max
+)

package/src/numbers/types.ts

@@ -0,0 +1,7 @@
+export type SpecialNumberString = '+Infinity' | '-Infinity' | 'Infinity' | 'NaN'
+
+export type NumberString<TStrict extends boolean = false> = SpecialNumberString | (TStrict extends true ? `${number}` : string)
+
+export type Numberish<TStrict extends boolean = false> = NumberString<TStrict> | bigint | number
+
+export type Percentage = { __brand: 'Percentage' } & number

package/src/objects/deep-merge.ts

@@ -0,0 +1,76 @@
+import type { AnyObject, DeepPartial } from './types'
+import { isArray } from '../arrays'
+import { unique } from '../arrays/set-operations'
+import { isPlainObject } from './guards'
+
+export type DeepMergeArrayMode = 'merge' | 'merge-dedupe' | 'replace'
+
+export interface DeepMergeOptions {
+    arrayMode?: DeepMergeArrayMode
+}
+
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+function mergeArrays(base: unknown[], override: unknown[], arrayMode: DeepMergeArrayMode): unknown[] {
+    if (arrayMode === 'replace') {
+        return override.map(deepCloneValue)
+    }
+
+    const merged = [...base, ...override]
+    const deduped = arrayMode === 'merge-dedupe' ? unique(merged) : merged
+
+    return deduped.map(deepCloneValue)
+}
+
+function deepCloneValue(value: unknown): unknown {
+    if (isPlainObject(value)) {
+        const cloned: Record<string, unknown> = {}
+
+        for (const key of Object.keys(value)) {
+            if (!DANGEROUS_KEYS.has(key)) {
+                cloned[key] = deepCloneValue(value[key])
+            }
+        }
+
+        return cloned
+    }
+
+    if (isArray(value)) {
+        return value.map(deepCloneValue)
+    }
+
+    return value
+}
+
+function mergeRecursive(base: Record<string, unknown>, override: Record<string, unknown>, arrayMode: DeepMergeArrayMode): Record<string, unknown> {
+    const result: Record<string, unknown> = {}
+
+    for (const key of Object.keys(base)) {
+        if (!DANGEROUS_KEYS.has(key)) {
+            result[key] = deepCloneValue(base[key])
+        }
+    }
+
+    for (const key of Object.keys(override)) {
+        if (DANGEROUS_KEYS.has(key)) {
+            continue
+        }
+
+        const baseVal = result[key]
+        const overrideVal = override[key]
+
+        if (isPlainObject(baseVal) && isPlainObject(overrideVal)) {
+            result[key] = mergeRecursive(baseVal, overrideVal, arrayMode)
+        } else if (isArray(baseVal) && isArray(overrideVal)) {
+            result[key] = mergeArrays(baseVal, overrideVal, arrayMode)
+        } else {
+            result[key] = deepCloneValue(overrideVal)
+        }
+    }
+
+    return result
+}
+
+export const deepMerge = <T extends AnyObject>(base: T, override: DeepPartial<T>, { arrayMode = 'replace' }: DeepMergeOptions = {}): T => (
+    mergeRecursive(base, override as Record<string, unknown>, arrayMode) as T
+)

package/src/objects/guards.ts

@@ -0,0 +1,21 @@
+import type { AnyObject, UnknownObject } from './types'
+import { isArray } from '../arrays'
+import { toString } from '../core'
+
+export const isObject = (value: unknown): value is AnyObject => value !== null && typeof value === 'object' && !isArray(value)
+
+export const isPlainObject = (value: unknown): value is UnknownObject => {
+    if (toString(value) !== '[object Object]') {
+        return false
+    }
+
+    const proto = Object.getPrototypeOf(value)
+
+    return proto === null || proto === Object.prototype
+}
+
+export const isEmptyObject = (value: AnyObject) => Object.keys(value).length === 0
+
+export const isKeyOf = <T extends AnyObject>(obj: T, name: PropertyKey): name is keyof T => name in obj
+
+export const isKeysOf = <T extends PropertyKey>(data: AnyObject, ...keys: T[]): data is Record<T, unknown> => keys.every((key) => isKeyOf(data, key))

package/src/objects/index.ts

@@ -0,0 +1,5 @@
+export * from './deep-merge'
+export * from './guards'
+export * from './transformations'
+
+export type * from './types'

package/src/objects/transformations.ts

@@ -0,0 +1,34 @@
+import type { AnyObject, FilterPredicate } from './types'
+import { isNullish, type Nullish } from '../core'
+
+export const entries = <O extends AnyObject>(obj: O) => Object.entries(obj) as Array<[keyof O, O[keyof O]]>
+
+export const filter = <O extends AnyObject>(obj: O, predicate: FilterPredicate<O, keyof O>): Partial<O> => (
+    Object.fromEntries(entries(obj).filter(([key, value], index) => predicate(key, value, index))) as Partial<O>
+)
+
+export const filterByValue = <O extends AnyObject>(obj: O, predicate: (value: O[keyof O]) => boolean) => filter(obj, (_, value) => predicate(value))
+
+export const pick = <O extends AnyObject, K extends keyof O>(obj: O, ...keys: K[]) => {
+    const set = new Set<PropertyKey>(keys)
+
+    return filter(obj, (key) => set.has(key)) as Pick<O, K>
+}
+
+export const omit = <O extends AnyObject, K extends keyof O>(object: O, ...keys: K[]) => {
+    const set = new Set<PropertyKey>(keys)
+
+    return filter(object, (key) => !set.has(key)) as Omit<O, K>
+}
+
+export const map = <K extends PropertyKey, V, NK extends PropertyKey, NV>(obj: Record<K, V>, fn: (k: K, v: V, i: number) => [NK, NV]) => (
+    Object.fromEntries(entries(obj).map(([k, v], i) => fn(k, v, i))) as Record<NK, NV>
+)
+
+export function resolveOptions<T extends AnyObject>(options: Nullish<T | boolean>, defaultValue: T | false): T | false {
+    if (options === false) {
+        return false
+    }
+
+    return isNullish(options) || options === true ? defaultValue : options
+}

package/src/objects/types.ts

@@ -0,0 +1,33 @@
+import type { Primitive } from '../core'
+
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+export type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>
+
+export type Mutable<T> = { -readonly [K in keyof T]: T[K] }
+
+export type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
+
+export type DeepReadonly<T> = T extends Primitive ? T : T extends Array<infer U> ? ReadonlyArray<DeepReadonly<U>> : { readonly [K in keyof T]: DeepReadonly<T[K]> }
+
+export type KeysOfType<T, V> = { [K in keyof T]-?: T[K] extends V ? K : never }[keyof T]
+
+export type StringKeys<T> = Extract<keyof T, string>
+
+export type Dictionary<T = unknown> = Record<string, T>
+
+export type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = T extends Record<K, V> ? T : never
+
+export type AnyObject = Record<string, any>
+
+export type UnknownObject = Record<string, unknown>
+
+export type Constructor<T> = new (...args: any[]) => T
+
+export type ClassMethods<T> = { [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never }[keyof T]
+
+export type ClassMethodArgs<T, M extends ClassMethods<T>> = T[M] extends (...args: infer A) => any ? A : never
+
+export type ClassMethodReturn<T, M extends ClassMethods<T>> = T[M] extends (...args: any[]) => infer R ? R : never
+
+export type FilterPredicate<O, K extends keyof O> = (key: K, value: O[K], index: number) => boolean

package/src/promises/abortable.ts

@@ -0,0 +1,37 @@
+import { createAbortError, ensureError, type Errorable } from '../errors'
+
+export function abortable<T>(promise: Promise<T>, signal?: AbortSignal, error?: Errorable): Promise<T> {
+    if (!signal) {
+        return promise
+    }
+
+    const createError = () => (error ? ensureError(error) : (signal.reason ?? createAbortError()))
+
+    if (signal.aborted) {
+        return Promise.reject(createError())
+    }
+
+    return new Promise<T>((resolve, reject) => {
+        let isSettled = false
+        let onAbort: () => void
+
+        const cleanup = (afterCleanup?: () => void) => {
+            if (!isSettled) {
+                isSettled = true
+                signal.removeEventListener('abort', onAbort)
+                afterCleanup?.()
+            }
+        }
+
+        onAbort = () => {
+            cleanup(() => reject(createError()))
+        }
+
+        signal.addEventListener('abort', onAbort)
+
+        promise.then(
+            (value) => cleanup(() => resolve(value)),
+            (error_) => cleanup(() => reject(error_)),
+        )
+    })
+}

package/src/promises/compositions.ts

@@ -0,0 +1,18 @@
+import type { Awaitable } from './types'
+
+export const pTap = <T>(fn: (value: T) => Awaitable<unknown>) => async (value: T): Promise<T> => {
+    return Promise.resolve(fn(value)).then(() => value)
+}
+
+pTap.catch = (fn: (error: unknown) => Awaitable<unknown>) => async (error: unknown): Promise<never> => {
+    await fn(error)
+    throw error
+}
+
+export async function tryCatchAsync<T>(fn: () => Awaitable<T>, fallback: (error: unknown) => Awaitable<T>) {
+    try {
+        return await fn()
+    } catch (error) {
+        return await fallback(error)
+    }
+}

package/src/promises/deferred.ts

@@ -0,0 +1,131 @@
+import { combineSignals, createAbortController, createAbortError, type Errorable } from '../errors'
+
+export interface DeferredPromiseOptions<T> {
+    onCallbackError?: (error: unknown) => void
+    onReject?: (reason: unknown) => void
+    onResolve?: (value: PromiseLike<T> | T) => void
+    onSettle?: () => void
+    signal?: AbortSignal
+    synchronousCallbacks?: boolean
+}
+
+export interface DeferredPromise<T> extends Promise<T> {
+    isPending: boolean
+    isRejected: boolean
+    isResolved: boolean
+    isSettled: boolean
+    reject: (reason?: unknown) => void
+    resolve: (value: PromiseLike<T> | T) => void
+}
+
+export function cleanupAbortSignal(signal: AbortSignal | undefined, abortHandler: (() => void) | undefined) {
+    if (abortHandler) {
+        signal?.removeEventListener('abort', abortHandler)
+    }
+}
+
+export function setupAbortSignal(signal: AbortSignal | undefined, onAbort: () => void) {
+    const abortHandler = () => onAbort()
+
+    if (signal?.aborted) {
+        onAbort()
+    } else {
+        signal?.addEventListener('abort', abortHandler)
+    }
+
+    return abortHandler
+}
+
+export function invokeSettleCallback(cb: () => void, onSettle: (() => void) | undefined, onCallbackError: ((error: unknown) => void) | undefined, synchronousCallbacks: boolean) {
+    const callback = () => {
+        try {
+            cb()
+        } catch (error) {
+            onCallbackError?.(error)
+        }
+
+        try {
+            onSettle?.()
+        } catch (error) {
+            onCallbackError?.(error)
+        }
+    }
+
+    if (synchronousCallbacks) {
+        callback()
+    } else {
+        queueMicrotask(callback)
+    }
+}
+
+export function createDeferred<T>({ onCallbackError, onReject, onResolve, onSettle, signal, synchronousCallbacks = false }: DeferredPromiseOptions<T> = {}): DeferredPromise<T> {
+    let resolveFn: (value: PromiseLike<T> | T) => void
+    let rejectFn: (reason?: unknown) => void
+    let abortHandler: (() => void) | undefined
+
+    let isSettled = false
+    let isResolved = false
+    let isRejected = false
+
+    const promise = <DeferredPromise<T>> new Promise<T>((resolve, reject) => {
+        resolveFn = resolve
+        rejectFn = reject
+    })
+
+    const afterSettle = (cb: () => void) => {
+        cleanupAbortSignal(signal, abortHandler)
+        invokeSettleCallback(cb, onSettle, onCallbackError, synchronousCallbacks)
+    }
+
+    Object.defineProperty(promise, 'isSettled', { enumerable: true, get: () => isSettled })
+    Object.defineProperty(promise, 'isPending', { enumerable: true, get: () => !isSettled })
+    Object.defineProperty(promise, 'isResolved', { enumerable: true, get: () => isResolved })
+    Object.defineProperty(promise, 'isRejected', { enumerable: true, get: () => isRejected })
+
+    promise.resolve = (value: PromiseLike<T> | T) => {
+        if (isSettled) {
+            return
+        }
+
+        isSettled = true
+        isResolved = true
+
+        resolveFn(value)
+        afterSettle(() => onResolve?.(value))
+    }
+
+    promise.reject = (reason?: unknown) => {
+        if (isSettled) {
+            return
+        }
+
+        isSettled = true
+        isRejected = true
+
+        rejectFn(reason)
+        afterSettle(() => onReject?.(reason))
+    }
+
+    abortHandler = setupAbortSignal(signal, () => {
+        promise.reject(signal?.reason ?? createAbortError())
+    })
+
+    return promise
+}
+
+export interface DeferredPromiseWithTimeoutOptions<T> extends DeferredPromiseOptions<T> {
+    error?: Errorable
+}
+
+export const createDeferredWithTimeout = <T>(ms: number, { error, signal, ...options }: DeferredPromiseWithTimeoutOptions<T> = {}) => {
+    const timeoutController = createAbortController(ms, error)
+
+    return createDeferred<T>({
+        ...options,
+        onSettle() {
+            timeoutController.abort()
+            options.onSettle?.()
+        },
+        signal: combineSignals(signal, timeoutController.signal),
+    })
+}

package/src/promises/guards.ts

@@ -0,0 +1,8 @@
+import { isFunction } from '../functions'
+import { isObject } from '../objects'
+
+export const isPromiseLike = <T>(value: unknown): value is PromiseLike<T> => isObject(value) && isFunction(value.then)
+
+export const isPromise = <T>(value: unknown): value is Promise<T> => (
+    isObject(value) && isFunction(value.then) && isFunction(value.catch) && isFunction(value.finally)
+)

package/src/promises/index.ts

@@ -0,0 +1,10 @@
+export * from './abortable'
+export * from './compositions'
+export * from './deferred'
+export * from './guards'
+export * from './pipe'
+export * from './poll'
+export * from './retry'
+export * from './timers'
+
+export type * from './types'