@kdtlabs/utils 0.0.4 → 0.0.6

package/src/common/guards.ts

@@ -0,0 +1,58 @@
+import { isArray, isEmptyArray } from '../arrays'
+import { isCollectionLike, isEmptyCollection } from '../collections'
+import { isNullish, isPrimitive, isString } from '../core'
+import { isEmptyObject, isPlainObject } from '../objects'
+
+export function isEmpty(value: unknown) {
+    if (isNullish(value)) {
+        return true
+    }
+
+    if (isArray(value)) {
+        return isEmptyArray(value)
+    }
+
+    if (isPrimitive(value)) {
+        if (isString(value)) {
+            return value.length === 0
+        }
+
+        return false
+    }
+
+    if (isPlainObject(value)) {
+        return isEmptyObject(value)
+    }
+
+    if (isCollectionLike(value)) {
+        return isEmptyCollection(value)
+    }
+
+    return false
+}
+
+export function isDeepEqual(a: unknown, b: unknown): boolean {
+    if (a === b) {
+        return true
+    }
+
+    if (isArray(a) && isArray(b)) {
+        if (a.length !== b.length) {
+            return false
+        }
+
+        return a.every((item, i) => isDeepEqual(item, b[i]))
+    }
+
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const keysA = Object.keys(a)
+
+        if (keysA.length !== Object.keys(b).length) {
+            return false
+        }
+
+        return keysA.every((key) => isDeepEqual(a[key], b[key]))
+    }
+
+    return Object.is(a, b)
+}

package/src/common/index.ts

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

package/src/common/transformations.ts

@@ -0,0 +1,20 @@
+import type { NullToUndefined } from './types'
+import { isArray } from '../arrays'
+import { isNullish } from '../core'
+import { isPlainObject, map } from '../objects'
+
+export function nullToUndefined<T>(value: T): NullToUndefined<T> {
+    if (isNullish(value)) {
+        return undefined as NullToUndefined<T>
+    }
+
+    if (isArray(value)) {
+        return value.map(nullToUndefined) as NullToUndefined<T>
+    }
+
+    if (isPlainObject(value)) {
+        return map(value, (k, v) => [k, nullToUndefined(v)]) as NullToUndefined<T>
+    }
+
+    return value as NullToUndefined<T>
+}

package/src/common/types.ts

@@ -0,0 +1,3 @@
+import type { AnyObject } from '../objects'
+
+export type NullToUndefined<T> = T extends null ? undefined : T extends Array<infer U> ? Array<NullToUndefined<U>> : T extends AnyObject ? { [K in keyof T]: NullToUndefined<T[K]> } : T

package/src/core/constants.ts

@@ -0,0 +1 @@
+export const DEFAULT_TRUE_STRINGS = new Set(['1', 'on', 'true', 'yes'])

package/src/core/conversions.ts

@@ -0,0 +1,9 @@
+export const toString = (value: unknown) => Object.prototype.toString.call(value)
+
+export function typeOf(value: unknown): string {
+    if (value === null) {
+        return 'null'
+    }
+
+    return typeof value === 'object' || typeof value === 'function' ? toString(value).slice(8, -1).toLowerCase() : typeof value
+}

package/src/core/guards.ts

@@ -0,0 +1,57 @@
+import type { JsonablePrimitive, Primitive } from './types'
+import { DEFAULT_TRUE_STRINGS } from './constants'
+
+export const isNull = (value: unknown): value is null => value === null
+export const isUndefined = (value: unknown): value is undefined => value === undefined
+export const isNullish = (value: unknown): value is null | undefined => isNull(value) || isUndefined(value)
+
+export const notNull = <T>(value: T): value is Exclude<T, null> => !isNull(value)
+export const notUndefined = <T>(value: T): value is Exclude<T, undefined> => !isUndefined(value)
+export const notNullish = <T>(value: T): value is NonNullable<T> => !isNullish(value)
+
+export const isBoolean = (value: unknown): value is boolean => typeof value === 'boolean'
+export const isSymbol = (value: unknown): value is symbol => typeof value === 'symbol'
+export const isBigInt = (value: unknown): value is bigint => typeof value === 'bigint'
+export const isNumber = (value: unknown): value is number => typeof value === 'number'
+export const isString = (value: unknown): value is string => typeof value === 'string'
+export const isDate = (value: unknown): value is Date => value instanceof Date
+
+export const isPrimitive = (value: unknown): value is Primitive => value === null || (typeof value !== 'object' && typeof value !== 'function')
+
+export const isJsonablePrimitive = (value: unknown): value is JsonablePrimitive => (
+    isNull(value) || isString(value) || isBoolean(value) || (isNumber(value) && Number.isFinite(value))
+)
+
+export interface IsTrueLikeOptions {
+    anyNonZeroNumber?: boolean
+    trueStrings?: Set<string>
+}
+
+export function isTrueLike(value: unknown, options: IsTrueLikeOptions = {}) {
+    const { anyNonZeroNumber = false, trueStrings = DEFAULT_TRUE_STRINGS } = options
+
+    if (isBoolean(value)) {
+        return value
+    }
+
+    if (isString(value)) {
+        return trueStrings.has(value.toLowerCase())
+    }
+
+    if (isNumber(value)) {
+        return anyNonZeroNumber ? value !== 0 && Number.isFinite(value) : value === 1
+    }
+
+    if (isBigInt(value)) {
+        return anyNonZeroNumber ? value !== 0n : value === 1n
+    }
+
+    return false
+}
+
+export const isGenerator = (value: unknown): boolean => (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Record<PropertyKey, unknown>).next === 'function' &&
+    typeof (value as Record<PropertyKey, unknown>)[Symbol.iterator] === 'function'
+)

package/src/core/index.ts

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

package/src/core/types.ts

@@ -0,0 +1,15 @@
+export type Primitive = bigint | boolean | number | string | symbol | null | undefined
+
+export type Optional<T> = T | undefined
+
+export type Nullable<T> = T | null
+
+export type Nullish<T> = T | null | undefined
+
+export type Never<T extends never = never> = T
+
+export type IsContainsType<T, U> = Extract<T, U> extends never ? false : true
+
+export type JsonablePrimitive = boolean | number | string | null
+
+export type Jsonable = Jsonable[] | JsonablePrimitive | { [key: string]: Jsonable }

package/src/errors/base-error.ts

@@ -0,0 +1,48 @@
+export type BaseErrorCode = number | string
+
+export interface BaseErrorOptions extends ErrorOptions {
+    cause?: unknown
+    code?: BaseErrorCode
+    details?: string
+    exitCode?: number
+    name?: string
+    retryable?: boolean
+    timestamp?: Date
+}
+
+export class BaseError extends Error {
+    public declare readonly timestamp: Date
+    public declare readonly code?: BaseErrorCode
+    public declare readonly cause?: unknown
+    public declare readonly details?: string
+    public declare readonly exitCode?: number
+    public declare readonly retryable?: boolean
+
+    public constructor(message: string, { code, details, exitCode, name, retryable, timestamp, ...options }: BaseErrorOptions = {}) {
+        super(message, options)
+
+        Object.setPrototypeOf(this, new.target.prototype)
+
+        this.defineValue('name', name ?? this.constructor.name)
+        this.defineValue('timestamp', timestamp ?? new Date())
+        this.defineValue('cause', options.cause)
+        this.defineValue('code', code)
+        this.defineValue('details', details)
+        this.defineValue('exitCode', exitCode)
+        this.defineValue('retryable', retryable)
+    }
+
+    public withValue<K extends string, V>(key: K, value: V): Record<K, V> & this {
+        if (Object.hasOwn(this, key)) {
+            throw new TypeError(`Cannot redefine property '${key}' on ${this.name}`)
+        }
+
+        return this.defineValue(key, value) as Record<K, V> & this
+    }
+
+    protected defineValue(key: string, value: unknown) {
+        Object.defineProperty(this, key, { configurable: false, enumerable: true, value, writable: false })
+
+        return this
+    }
+}

package/src/errors/factories.ts

@@ -0,0 +1,74 @@
+import type { Errorable, ErrorCtor, ErrorLike } from './types'
+import { isString, notNullish } from '../core'
+import { isErrorLike } from './guards'
+
+export const createAbortError = (message = 'This operation was aborted', name = 'AbortError') => new DOMException(message, name)
+
+export const createTimeoutError = (message = 'The operation was aborted due to a timeout', name = 'TimeoutError') => createAbortError(message, name)
+
+export function createAbortController(timeout?: number, timeoutError?: Errorable) {
+    const controller = new AbortController()
+
+    if (notNullish(timeout) && timeout > 0 && timeout <= Number.MAX_SAFE_INTEGER) {
+        let timeoutId: NodeJS.Timeout
+
+        const cleanup = () => {
+            clearTimeout(timeoutId)
+            controller.signal.removeEventListener('abort', cleanup)
+        }
+
+        controller.signal.addEventListener('abort', cleanup)
+        timeoutId = setTimeout(() => controller.abort(ensureError(timeoutError ?? createTimeoutError())), timeout)
+    }
+
+    return controller
+}
+
+export function ensureError(input: Errorable, ctor?: ErrorCtor) {
+    if (typeof input === 'string') {
+        return ctor ? new ctor(input) : new Error(input)
+    }
+
+    if (typeof input === 'function') {
+        return ensureError(input(), ctor)
+    }
+
+    return input
+}
+
+export function fromErrorLike({ cause, message, name, stack, ...properties }: ErrorLike, ctor?: ErrorCtor) {
+    const errorClass = ctor ?? Error
+    const error = new errorClass(message, { cause })
+
+    Object.defineProperty(error, 'name', { configurable: true, enumerable: false, value: name, writable: true })
+    Object.defineProperty(error, 'stack', { configurable: true, enumerable: false, value: stack, writable: true })
+
+    for (const [key, value] of Object.entries(properties)) {
+        Object.defineProperty(error, key, Object.getOwnPropertyDescriptor(properties, key) ?? { configurable: true, enumerable: true, value, writable: true })
+    }
+
+    return error
+}
+
+export interface NormalizeErrorOptions {
+    defaultMessage?: string
+    errorConstructor?: ErrorCtor
+}
+
+export function normalizeError(error: unknown, { defaultMessage = 'Unknown error', errorConstructor }: NormalizeErrorOptions = {}) {
+    const errorClass = errorConstructor ?? Error
+
+    if (error instanceof errorClass) {
+        return error
+    }
+
+    if (isString(error)) {
+        return ensureError(error, errorConstructor)
+    }
+
+    if (isErrorLike(error)) {
+        return fromErrorLike(error, errorConstructor)
+    }
+
+    return new errorClass(defaultMessage, { cause: error })
+}

package/src/errors/guards.ts

@@ -0,0 +1,12 @@
+import type { ErrorLike } from './types'
+import { isString } from '../core'
+import { isKeysOf, isObject } from '../objects'
+import { BaseError } from './base-error'
+
+export const isError = (value: unknown): value is Error => value instanceof Error
+
+export const isBaseError = (value: unknown): value is BaseError => value instanceof BaseError
+
+export const isAbortError = (error: unknown): error is DOMException => error instanceof DOMException && error.name === 'AbortError'
+
+export const isErrorLike = (value: unknown): value is ErrorLike => isObject(value) && isKeysOf(value, 'name') && isString(value.name)

package/src/errors/index.ts

@@ -0,0 +1,7 @@
+export * from './base-error'
+export * from './factories'
+export * from './guards'
+export * from './operations'
+export * from './stringify'
+
+export type * from './types'

package/src/errors/operations.ts

@@ -0,0 +1,15 @@
+import { notNullish, type Nullish } from '../core'
+
+export function combineSignals(...signals: Array<Nullish<AbortSignal>>) {
+    const validSignals = signals.filter(notNullish)
+
+    if (validSignals.length === 0) {
+        return new AbortController().signal
+    }
+
+    if (validSignals.length === 1) {
+        return validSignals[0]!
+    }
+
+    return AbortSignal.any(validSignals)
+}

package/src/errors/stringify.ts

@@ -0,0 +1,131 @@
+import { isString, notNullish } from '../core'
+import { isObject } from '../objects'
+import { normalizeError, type NormalizeErrorOptions } from './factories'
+
+export interface StringifyErrorFormatters {
+    code?: (code: string) => string
+    message?: (message: string) => string
+    name?: (name: string) => string
+}
+
+export interface StringifyErrorOptions extends NormalizeErrorOptions {
+    causeIndent?: number
+    causePrefix?: string
+    circularReferenceMessage?: string
+    formatters?: StringifyErrorFormatters
+    includeCause?: boolean
+    includeCode?: boolean
+    includeName?: boolean
+    maxCauseDepth?: number
+}
+
+export const DEFAULT_STRINGIFY_FORMATTERS: Required<StringifyErrorFormatters> = {
+    code: (value) => `[${value}]`,
+    message: (value) => value,
+    name: (value) => `${value}:`,
+}
+
+export interface StringifyErrorState {
+    causeIndent: number
+    causePrefix: string
+    circularReferenceMessage: string
+    defaultMessage: string
+    formatters: Required<StringifyErrorFormatters>
+    includeCause: boolean
+    includeCode: boolean
+    includeName: boolean
+    maxCauseDepth: number
+    normalizeOptions: NormalizeErrorOptions
+    visited: Set<unknown>
+}
+
+export function collectCauses(error: Error, depth: number, indent: string, state: StringifyErrorState) {
+    const childIndent = indent + ' '.repeat(state.causeIndent)
+    const pointers: string[] = []
+
+    if (error instanceof AggregateError && error.errors.length > 0) {
+        for (const subError of error.errors) {
+            pointers.push(stringifyErrorNode(subError, depth - 1, childIndent, state.causePrefix, state))
+        }
+    }
+
+    if (isObject(error.cause) || isString(error.cause)) {
+        pointers.push(stringifyErrorNode(error.cause, depth - 1, childIndent, state.causePrefix, state))
+    }
+
+    return pointers
+}
+
+export function appendCauses(parts: string[], error: Error, error_: unknown, depth: number, indent: string, state: StringifyErrorState) {
+    if (!state.includeCause || depth <= 0 || (error !== error_ && error.cause === error_)) {
+        return
+    }
+
+    const pointers = collectCauses(error, depth, indent, state)
+
+    if (pointers.length > 0) {
+        parts.push(`\n${pointers.join('\n')}`)
+    }
+}
+
+export function buildErrorParts(error: Error, state: StringifyErrorState) {
+    const parts: string[] = []
+
+    if (state.includeCode && 'code' in error && notNullish(error.code)) {
+        parts.push(state.formatters.code(String(error.code)))
+    }
+
+    if (state.includeName) {
+        parts.push(state.formatters.name(error.name))
+    }
+
+    parts.push(state.formatters.message(error.message || state.defaultMessage))
+
+    return parts
+}
+
+export function stringifyErrorNode(error_: unknown, depth: number, indent: string, prefix: string, state: StringifyErrorState): string {
+    if (state.visited.has(error_)) {
+        return `${indent}${prefix}${state.circularReferenceMessage}`
+    }
+
+    if (error_ instanceof Error) {
+        state.visited.add(error_)
+    }
+
+    if (error_ instanceof Error && error_.toString !== Error.prototype.toString) {
+        const parts = [error_.toString()]
+        appendCauses(parts, error_, error_, depth, indent, state)
+
+        return indent + prefix + parts.join(' ')
+    }
+
+    const error = normalizeError(error_, { ...state.normalizeOptions, defaultMessage: state.defaultMessage })
+
+    state.visited.add(error)
+
+    const parts = buildErrorParts(error, state)
+    appendCauses(parts, error, error_, depth, indent, state)
+
+    return indent + prefix + parts.join(' ')
+}
+
+export function stringifyError(error: unknown, options: StringifyErrorOptions = {}) {
+    const { causeIndent = 2, causePrefix = '-> ', circularReferenceMessage = '[Circular Reference]', defaultMessage = 'Unknown error', formatters: formatters_ = {}, includeCause = true, includeCode = true, includeName = true, maxCauseDepth = Number.POSITIVE_INFINITY, ...normalizeOptions } = options
+
+    const state: StringifyErrorState = {
+        causeIndent,
+        causePrefix,
+        circularReferenceMessage,
+        defaultMessage,
+        formatters: { ...DEFAULT_STRINGIFY_FORMATTERS, ...formatters_ },
+        includeCause,
+        includeCode,
+        includeName,
+        maxCauseDepth,
+        normalizeOptions,
+        visited: new Set<unknown>(),
+    }
+
+    return stringifyErrorNode(error, maxCauseDepth, '', '', state)
+}

package/src/errors/types.ts

@@ -0,0 +1,11 @@
+export type Errorable = Error | (() => Error | string) | string
+
+export type ErrorCtor = new (message?: string, options?: ErrorOptions) => Error
+
+export interface ErrorLike {
+    [key: string]: unknown
+    cause?: unknown
+    message?: string
+    name: string
+    stack?: string
+}

package/src/events/emitter.ts

@@ -0,0 +1,117 @@
+import type { EventArgs, EventListener, EventListenerMap, EventMap, EventNames } from './types'
+
+export class Emitter<TEventMap = EventMap, TStrict extends boolean = false> {
+    protected readonly eventListeners: EventListenerMap
+    protected readonly onceListeners: EventListenerMap
+
+    public constructor() {
+        this.eventListeners = new Map()
+        this.onceListeners = new Map()
+    }
+
+    public listeners<TEventName extends EventNames<TEventMap, TStrict>>(eventName: TEventName): Array<EventListener<EventArgs<TEventMap, TEventName, TStrict>>> {
+        const listeners = this.eventListeners.get(eventName) ?? []
+        const onceListeners = this.onceListeners.get(eventName) ?? []
+
+        return [...listeners, ...onceListeners]
+    }
+
+    public listenersCount<TEventName extends EventNames<TEventMap, TStrict>>(eventName: TEventName) {
+        const listeners = this.eventListeners.get(eventName)
+        const onceListeners = this.onceListeners.get(eventName)
+
+        return (listeners?.size ?? 0) + (onceListeners?.size ?? 0)
+    }
+
+    public eventNames(): Array<PropertyKey | keyof TEventMap> {
+        return [...new Set([...this.eventListeners.keys(), ...this.onceListeners.keys()])]
+    }
+
+    public on<TEventName extends EventNames<TEventMap, TStrict>>(eventName: TEventName, listener: EventListener<EventArgs<TEventMap, TEventName, TStrict>>): this {
+        this.#addTo(this.eventListeners, eventName, listener)
+
+        return this
+    }
+
+    public once<TEventName extends EventNames<TEventMap, TStrict>>(eventName: TEventName, listener: EventListener<EventArgs<TEventMap, TEventName, TStrict>>): this {
+        this.#addTo(this.onceListeners, eventName, listener)
+
+        return this
+    }
+
+    public off<TEventName extends EventNames<TEventMap, TStrict>>(eventName: TEventName, listener: EventListener<EventArgs<TEventMap, TEventName, TStrict>>): this {
+        this.#removeFrom(this.eventListeners, eventName, listener)
+        this.#removeFrom(this.onceListeners, eventName, listener)
+
+        return this
+    }
+
+    public emit<TEventName extends EventNames<TEventMap, TStrict>>(eventName: TEventName, ...args: EventArgs<TEventMap, TEventName, TStrict>): boolean {
+        const regularSnapshot = this.#takeSnapshot(this.eventListeners.get(eventName))
+        const onceSnapshot = this.#takeSnapshot(this.onceListeners.get(eventName))
+
+        this.onceListeners.delete(eventName)
+
+        const fromRegular = this.#emitSnapshot(regularSnapshot, args)
+        const fromOnce = this.#emitSnapshot(onceSnapshot, args)
+
+        return fromRegular || fromOnce
+    }
+
+    public removeAllListeners<TEventName extends EventNames<TEventMap, TStrict>>(eventName?: TEventName): this {
+        if (eventName === undefined) {
+            this.eventListeners.clear()
+            this.onceListeners.clear()
+        } else {
+            this.eventListeners.delete(eventName)
+            this.onceListeners.delete(eventName)
+        }
+
+        return this
+    }
+
+    #addTo(map: EventListenerMap, eventName: PropertyKey, listener: EventListener) {
+        let set = map.get(eventName)
+
+        if (!set) {
+            set = new Set()
+            map.set(eventName, set)
+        }
+
+        set.add(listener)
+    }
+
+    #removeFrom(map: EventListenerMap, eventName: PropertyKey, listener: EventListener) {
+        const set = map.get(eventName)
+
+        if (!set) {
+            return
+        }
+
+        set.delete(listener)
+
+        if (set.size === 0) {
+            map.delete(eventName)
+        }
+    }
+
+    #takeSnapshot(set: Set<EventListener> | undefined) {
+        if (!set || set.size === 0) {
+            return []
+        }
+
+        return [...set]
+    }
+
+    #emitSnapshot(snapshot: EventListener[], args: any[]) {
+        if (snapshot.length === 0) {
+            return false
+        }
+
+        for (const listener of snapshot) {
+            listener(...args)
+        }
+
+        return true
+    }
+}

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export * from './emitter'
+export type * from './types'

package/src/events/types.ts

@@ -0,0 +1,11 @@
+export type EventMap = Record<PropertyKey, any[]>
+
+export type EventNames<TEventMap, TStrict extends boolean> = TStrict extends true ? keyof TEventMap : keyof TEventMap | string
+
+export type ResolveEventArgs<TEventMap, TEventName> = TEventName extends keyof TEventMap ? TEventMap[TEventName] extends any[] ? TEventMap[TEventName] : any[] : any[]
+
+export type EventArgs<TEventMap, TEventName, TStrict extends boolean> = TStrict extends true ? TEventName extends keyof TEventMap ? ResolveEventArgs<TEventMap, TEventName> : never : ResolveEventArgs<TEventMap, TEventName>
+
+export type EventListener<TArgs = any[]> = (...args: TArgs extends any[] ? TArgs : any[]) => void
+
+export type EventListenerMap = Map<PropertyKey, Set<EventListener>>

package/src/functions/compositions.ts

@@ -0,0 +1,17 @@
+import { isFunction } from './guards'
+
+export function tap<T>(value: T, callback: (value: T) => void) {
+    callback(value)
+
+    return value
+}
+
+export const transform = <T, R>(value: T, callback: (value: T) => R) => callback(value)
+
+export function tryCatch<T>(fn: () => T, fallback: T | ((error: unknown) => T)) {
+    try {
+        return fn()
+    } catch (error) {
+        return isFunction(fallback) ? fallback(error) : fallback
+    }
+}

package/src/functions/debounce.ts

@@ -0,0 +1,34 @@
+import type { Args, Fn, TimingControlled } from './types'
+import { createTimerState, flushTimer, invokeTimer } from './timer-state'
+
+export type Debounced<T extends Fn> = TimingControlled<T>
+
+export function debounce<T extends Fn>(fn: T, wait: number): Debounced<T> {
+    const state = createTimerState<T>()
+    const invoke = () => invokeTimer(state, fn)
+
+    const debounced: Debounced<T> = function (this: unknown, ...args: Args<T>) {
+        state.lastArgs = args
+        state.lastThis = this
+
+        if (state.timeoutId !== undefined) {
+            clearTimeout(state.timeoutId)
+        }
+
+        state.timeoutId = setTimeout(invoke, wait)
+    }
+
+    debounced.cancel = () => {
+        if (state.timeoutId !== undefined) {
+            clearTimeout(state.timeoutId)
+            state.timeoutId = undefined
+            state.lastArgs = undefined
+        }
+    }
+
+    debounced.flush = () => {
+        return flushTimer(state, invoke)
+    }
+
+    return debounced
+}