@kdtlabs/utils 0.0.4 → 0.0.5

package/src/functions/throttle.ts

@@ -0,0 +1,59 @@
+import type { Args, Fn, TimingControlled } from './types'
+import { createTimerState, flushTimer, invokeTimer } from './timer-state'
+
+export type Throttled<T extends Fn> = TimingControlled<T>
+
+export function throttle<T extends Fn>(fn: T, wait: number): Throttled<T> {
+    const state = createTimerState<T>()
+
+    let lastCallTime: number | undefined
+
+    const invoke = () => {
+        lastCallTime = Date.now()
+        invokeTimer(state, fn)
+    }
+
+    const throttled: Throttled<T> = function (this: unknown, ...args: Args<T>) {
+        const now = Date.now()
+
+        state.lastArgs = args
+        state.lastThis = this
+
+        if (lastCallTime === undefined) {
+            lastCallTime = now
+            state.lastResult = fn.apply(this, args)
+
+            return
+        }
+
+        const remaining = wait - (now - lastCallTime)
+
+        if (remaining <= 0) {
+            if (state.timeoutId !== undefined) {
+                clearTimeout(state.timeoutId)
+                state.timeoutId = undefined
+            }
+
+            lastCallTime = now
+            state.lastResult = fn.apply(this, args)
+        } else {
+            state.timeoutId ??= setTimeout(invoke, remaining)
+        }
+    }
+
+    throttled.cancel = () => {
+        if (state.timeoutId !== undefined) {
+            clearTimeout(state.timeoutId)
+            state.timeoutId = undefined
+        }
+
+        state.lastArgs = undefined
+        lastCallTime = undefined
+    }
+
+    throttled.flush = () => {
+        return flushTimer(state, invoke)
+    }
+
+    return throttled
+}

package/src/functions/timer-state.ts

@@ -0,0 +1,33 @@
+import type { Args, Fn } from './types'
+
+export interface TimerState<T extends Fn> {
+    lastArgs: Args<T> | undefined
+    lastResult: ReturnType<T> | undefined
+    lastThis: unknown
+    timeoutId: ReturnType<typeof setTimeout> | undefined
+}
+
+export const createTimerState = <T extends Fn>(): TimerState<T> => ({
+    lastArgs: undefined,
+    lastResult: undefined,
+    lastThis: undefined,
+    timeoutId: undefined,
+})
+
+export function invokeTimer<T extends Fn>(state: TimerState<T>, fn: T) {
+    const args = state.lastArgs!
+    const thisArg = state.lastThis
+
+    state.timeoutId = undefined
+    state.lastArgs = undefined
+    state.lastResult = fn.apply(thisArg, args)
+}
+
+export function flushTimer<T extends Fn>(state: TimerState<T>, invoke: () => void) {
+    if (state.timeoutId !== undefined) {
+        clearTimeout(state.timeoutId)
+        invoke()
+    }
+
+    return state.lastResult
+}

package/src/functions/types.ts

@@ -0,0 +1,8 @@
+export type Fn = (...args: any[]) => any
+
+export type Args<F extends Fn> = F extends (...args: infer A) => any ? A : never
+
+export type TimingControlled<T extends Fn> = ((...args: Args<T>) => void) & {
+    cancel: () => void
+    flush: () => ReturnType<T> | undefined
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from './arrays'
+export * from './buffers'
+export * from './collections'
+export * from './common'
+export * from './core'
+export * from './errors'
+export * from './events'
+export * from './functions'
+export * from './json-rpc'
+export * from './numbers'
+export * from './objects'
+export * from './promises'
+export * from './serializer'
+export * from './strings'
+export * from './system'
+export * from './times'

package/src/json-rpc/constants.ts

@@ -0,0 +1,15 @@
+export enum JsonRpcErrorCode {
+    ParseError = -32_700,
+    InternalError = -32_603,
+    InvalidParams = -32_602,
+    MethodNotFound = -32_601,
+    InvalidRequest = -32_600,
+}
+
+export const JSON_RPC_ERROR_MESSAGES: Record<JsonRpcErrorCode, string> = {
+    [JsonRpcErrorCode.InternalError]: 'Internal error',
+    [JsonRpcErrorCode.InvalidParams]: 'Invalid params',
+    [JsonRpcErrorCode.InvalidRequest]: 'Invalid request',
+    [JsonRpcErrorCode.MethodNotFound]: 'Method not found',
+    [JsonRpcErrorCode.ParseError]: 'Parse error',
+}

package/src/json-rpc/factories.ts

@@ -0,0 +1,22 @@
+import type { JsonRpcErrorObject, JsonRpcErrorResponseMessage, JsonRpcNotifyMessage, JsonRpcRequestMessage, JsonRpcResponseId, JsonRpcSuccessResponseMessage } from './types'
+import { notUndefined } from '../core'
+
+export const createJsonRpcNotifyMessage = <TParams>(method: string, params?: TParams): JsonRpcNotifyMessage<TParams> => ({
+    jsonrpc: '2.0', method, ...(notUndefined(params) ? { params } : {}),
+})
+
+export const createJsonRpcRequestMessage = <TParams>(id: number | string, method: string, params?: TParams): JsonRpcRequestMessage<TParams> => ({
+    id, jsonrpc: '2.0', method, ...(notUndefined(params) ? { params } : {}),
+})
+
+export const createJsonRpcSuccessResponseMessage = <TResult = any>(id: JsonRpcResponseId, result: TResult): JsonRpcSuccessResponseMessage<TResult> => ({
+    id, jsonrpc: '2.0', result,
+})
+
+export const createJsonRpcErrorObject = <TData>(code: number, message: string, data?: TData): JsonRpcErrorObject<TData> => ({
+    code, message, ...(notUndefined(data) ? { data } : {}),
+})
+
+export const createJsonRpcErrorResponseMessage = <TData>(id: JsonRpcResponseId, error: JsonRpcErrorObject<TData>): JsonRpcErrorResponseMessage<TData> => ({
+    error, id, jsonrpc: '2.0',
+})

package/src/json-rpc/guards.ts

@@ -0,0 +1,58 @@
+import type { JsonRpcBatchRequest, JsonRpcBatchResponse, JsonRpcErrorObject, JsonRpcErrorResponseMessage, JsonRpcMessage, JsonRpcNotifyMessage, JsonRpcRequestMessage, JsonRpcResponseId, JsonRpcResponseMessage, JsonRpcResponseMessageWithNonNullId, JsonRpcSuccessResponseMessage } from './types'
+import { isArray } from '../arrays'
+import { isNull, isNumber, isString, notNullish } from '../core'
+import { isKeysOf, isObject } from '../objects'
+
+export const isJsonRpcMessage = <TParams = any, TResult = any, TErrorData = any>(message: unknown): message is JsonRpcMessage<TParams, TResult, TErrorData> => (
+    isObject(message) && message.jsonrpc === '2.0'
+)
+
+export const isValidJsonRpcId = (id: unknown): id is JsonRpcResponseId => isString(id) || isNumber(id) || isNull(id)
+
+export const isJsonRpcRequestMessage = <TParams = any>(message: JsonRpcMessage): message is JsonRpcRequestMessage<TParams> => (
+    isKeysOf(message, 'id', 'method') && isValidJsonRpcId(message.id) && isString(message.method)
+)
+
+export const isJsonRpcNotifyMessage = <TParams = any>(message: JsonRpcMessage): message is JsonRpcNotifyMessage<TParams> => (
+    isKeysOf(message, 'method') && isString(message.method) && !isKeysOf(message, 'id')
+)
+
+export const isJsonRpcResponseMessage = <TResult = any, TErrorData = any>(message: JsonRpcMessage): message is JsonRpcResponseMessage<TResult, TErrorData> => (
+    isKeysOf(message, 'id') && isValidJsonRpcId(message.id) && !isKeysOf(message, 'method')
+)
+
+export const isJsonRpcError = <TData = any>(message: unknown): message is JsonRpcErrorObject<TData> => (
+    isObject(message) && isKeysOf(message, 'code', 'message')
+)
+
+export const isJsonRpcErrorResponseMessage = <TData = any>(message: JsonRpcMessage): message is JsonRpcErrorResponseMessage<TData> => (
+    isKeysOf(message, 'error') && isJsonRpcError(message.error)
+)
+
+export const isJsonRpcSuccessResponseMessage = <TResult = any>(message: JsonRpcMessage): message is JsonRpcSuccessResponseMessage<TResult> => (
+    isKeysOf(message, 'result') && !isKeysOf(message, 'error')
+)
+
+export const isJsonRpcResponseHasNonNullableId = <TResult = any, TErrorData = any>(response: JsonRpcResponseMessage): response is JsonRpcResponseMessageWithNonNullId<TResult, TErrorData> => (
+    notNullish(response.id)
+)
+
+export const isJsonRpcBatchRequest = <TParams = any>(value: unknown): value is JsonRpcBatchRequest<TParams> => (
+    isArray(value) && value.length > 0 && value.every((item) => {
+        if (!isJsonRpcMessage(item)) {
+            return false
+        }
+
+        return isJsonRpcRequestMessage(item) || isJsonRpcNotifyMessage(item)
+    })
+)
+
+export const isJsonRpcBatchResponse = <TResult = any, TErrorData = any>(value: unknown): value is JsonRpcBatchResponse<TResult, TErrorData> => (
+    isArray(value) && value.length > 0 && value.every((item) => {
+        if (!isJsonRpcMessage(item)) {
+            return false
+        }
+
+        return isJsonRpcResponseMessage(item)
+    })
+)

package/src/json-rpc/index.ts

@@ -0,0 +1,5 @@
+export * from './constants'
+export * from './factories'
+export * from './guards'
+
+export type * from './types'

package/src/json-rpc/types.ts

@@ -0,0 +1,48 @@
+export interface BaseJsonRpcMessage {
+    jsonrpc: '2.0'
+}
+
+export interface JsonRpcRequestMessage<TParams = any> extends BaseJsonRpcMessage {
+    id: number | string
+    method: string
+    params?: TParams
+}
+
+export interface JsonRpcNotifyMessage<TParams = any> extends BaseJsonRpcMessage {
+    method: string
+    params?: TParams
+}
+
+export interface JsonRpcErrorObject<TData = any> {
+    code: number
+    data?: TData
+    message: string
+}
+
+export type JsonRpcResponseId = number | string | null
+
+export interface BaseJsonRpcResponseMessage extends BaseJsonRpcMessage {
+    id: JsonRpcResponseId
+}
+
+export interface JsonRpcSuccessResponseMessage<TResult = any> extends BaseJsonRpcResponseMessage {
+    result: TResult
+}
+
+export interface JsonRpcErrorResponseMessage<TData = any> extends BaseJsonRpcResponseMessage {
+    error: JsonRpcErrorObject<TData>
+}
+
+export type JsonRpcResponseMessage<TResult = any, TErrorData = any> = JsonRpcErrorResponseMessage<TErrorData> | JsonRpcSuccessResponseMessage<TResult>
+
+export type JsonRpcResponseBodyWithoutId<TResult = any, TErrorData = any> = Omit<JsonRpcErrorResponseMessage<TErrorData>, 'id'> | Omit<JsonRpcSuccessResponseMessage<TResult>, 'id'>
+
+export type JsonRpcResponseMessageWithNonNullId<TResult = any, TErrorData = any> = JsonRpcResponseBodyWithoutId<TResult, TErrorData> & {
+    id: NonNullable<JsonRpcResponseId>
+}
+
+export type JsonRpcMessage<TParams = any, TResult = any, TErrorData = any> = JsonRpcNotifyMessage<TParams> | JsonRpcRequestMessage<TParams> | JsonRpcResponseMessage<TResult, TErrorData>
+
+export type JsonRpcBatchRequest<TParams = any> = Array<JsonRpcNotifyMessage<TParams> | JsonRpcRequestMessage<TParams>>
+
+export type JsonRpcBatchResponse<TResult = any, TErrorData = any> = Array<JsonRpcResponseMessage<TResult, TErrorData>>

package/src/numbers/bigint-math.ts

@@ -0,0 +1,163 @@
+export const BigIntMath = {
+    isEven(a: bigint) {
+        return a % 2n === 0n
+    },
+
+    isOdd(a: bigint) {
+        return a % 2n !== 0n
+    },
+
+    divMod(a: bigint, b: bigint): [quotient: bigint, remainder: bigint] {
+        if (b === 0n) {
+            throw new RangeError('Division by zero')
+        }
+
+        return [a / b, a % b]
+    },
+
+    abs(a: bigint) {
+        return a < 0n ? -a : a
+    },
+
+    max(a: bigint, b: bigint) {
+        return a > b ? a : b
+    },
+
+    min(a: bigint, b: bigint) {
+        return a < b ? a : b
+    },
+
+    pow(a: bigint, b: bigint) {
+        return a ** b
+    },
+
+    sign(a: bigint) {
+        return a === 0n ? 0n : (a < 0n ? -1n : 1n)
+    },
+
+    mod(a: bigint, b: bigint) {
+        return ((a % b) + b) % b
+    },
+
+    modPow(base: bigint, exponent: bigint, modulus: bigint) {
+        if (exponent < 0n) {
+            throw new RangeError('Exponent must be non-negative')
+        }
+
+        if (modulus === 1n) {
+            return 0n
+        }
+
+        let result = 1n
+
+        base = BigIntMath.mod(base, modulus)
+
+        while (exponent > 0n) {
+            if (exponent % 2n === 1n) {
+                result = BigIntMath.mod(result * base, modulus)
+            }
+
+            exponent >>= 1n
+            base = BigIntMath.mod(base * base, modulus)
+        }
+
+        return result
+    },
+
+    gcd(a: bigint, b: bigint) {
+        a = BigIntMath.abs(a)
+        b = BigIntMath.abs(b)
+
+        while (b !== 0n) {
+            [a, b] = [b, a % b]
+        }
+
+        return a
+    },
+
+    lcm(a: bigint, b: bigint) {
+        return (a / BigIntMath.gcd(a, b)) * b
+    },
+
+    clamp(value: bigint, min: bigint, max: bigint) {
+        return BigIntMath.min(BigIntMath.max(value, min), max)
+    },
+
+    sqrt(n: bigint) {
+        if (n < 0n) {
+            throw new RangeError('Square root of negative bigint is undefined')
+        }
+
+        if (n < 2n) {
+            return n
+        }
+
+        let x = n
+        let y = (x + 1n) / 2n
+
+        while (y < x) {
+            x = y
+            y = (x + n / x) / 2n
+        }
+
+        return x
+    },
+
+    factorial(n: bigint) {
+        if (n < 0n) {
+            throw new RangeError('Factorial of negative bigint is undefined')
+        }
+
+        if (n === 0n) {
+            return 1n
+        }
+
+        let result = 1n
+
+        for (let i = 1n; i <= n; i++) {
+            result *= i
+        }
+
+        return result
+    },
+
+    sum(array: bigint[]) {
+        return array.reduce((a, b) => a + b, 0n)
+    },
+
+    avg(array: bigint[]) {
+        if (array.length === 0) {
+            return 0n
+        }
+
+        return BigIntMath.sum(array) / BigInt(array.length)
+    },
+
+    isPrime(n: bigint) {
+        if (n < 2n) {
+            return false
+        }
+
+        if (n < 4n) {
+            return true
+        }
+
+        if (n % 2n === 0n || n % 3n === 0n) {
+            return false
+        }
+
+        const limit = BigIntMath.sqrt(n)
+
+        for (let i = 5n; i <= limit; i += 6n) {
+            if (n % i === 0n || n % (i + 2n) === 0n) {
+                return false
+            }
+        }
+
+        return true
+    },
+
+    compare(a: bigint, b: bigint) {
+        return a === b ? 0 : (a < b ? -1 : 1)
+    },
+}

package/src/numbers/constants.ts

@@ -0,0 +1,14 @@
+export const SPECIAL_NUMBER_STRINGS = new Set(['+Infinity', '-Infinity', 'Infinity', 'NaN'])
+
+export const SUBSCRIPT_CHARS: Record<string, string> = {
+    0: '\u2080',
+    1: '\u2081',
+    2: '\u2082',
+    3: '\u2083',
+    4: '\u2084',
+    5: '\u2085',
+    6: '\u2086',
+    7: '\u2087',
+    8: '\u2088',
+    9: '\u2089',
+}

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