@kdtlabs/utils 0.0.4 → 0.0.6

package/src/serializer/serializers/leaf-object.ts

@@ -0,0 +1,18 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext } from '../types'
+
+export function serializeLeafObject(value: unknown, ctx: SerializeContext): Jsonable | undefined {
+    if (value instanceof Date) {
+        return ctx.replacer({ type: 'date', value: value.toISOString() })
+    }
+
+    if (value instanceof RegExp) {
+        return ctx.replacer({ type: 'regexp', value: value.toString() })
+    }
+
+    if (value instanceof URL) {
+        return ctx.replacer({ type: 'url', value: value.href })
+    }
+
+    return undefined
+}

package/src/serializer/serializers/number.ts

@@ -0,0 +1,14 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext } from '../types'
+
+export function serializeNumber(value: number, ctx: SerializeContext): Jsonable {
+    if (Number.isNaN(value)) {
+        return ctx.replacer({ type: 'number', value: 'NaN' })
+    }
+
+    if (!Number.isFinite(value)) {
+        return ctx.replacer({ type: 'number', value: value > 0 ? 'Infinity' : '-Infinity' })
+    }
+
+    return value
+}

package/src/serializer/serializers/object.ts

@@ -0,0 +1,62 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext, SerializeValueFn } from '../types'
+import { OMIT_SENTINEL } from '../constants'
+
+export function handlePropertyAccessError(error: unknown, strategy: SerializeContext['onPropertyAccess'], key: string | symbol, ctx: SerializeContext): Jsonable | typeof OMIT_SENTINEL {
+    if (strategy === 'throw') {
+        throw error
+    }
+
+    if (strategy === 'omit') {
+        return OMIT_SENTINEL
+    }
+
+    return ctx.replacer({ type: 'property-access-error', value: `[Property Access Error: ${String(key)}]` })
+}
+
+export function safeAccess(obj: object, key: string | symbol, strategy: SerializeContext['onPropertyAccess'], ctx: SerializeContext): unknown {
+    try {
+        return (obj as Record<string | symbol, unknown>)[key]
+    } catch (error) {
+        return handlePropertyAccessError(error, strategy, key, ctx)
+    }
+}
+
+export function serializeObject(obj: object, ctx: SerializeContext, serializeValue: SerializeValueFn): Record<string, Jsonable> {
+    const result: Record<string, Jsonable> = {}
+    const { onPropertyAccess, symbolRegistry } = ctx
+
+    for (const key of Object.keys(obj)) {
+        const value = safeAccess(obj, key, onPropertyAccess, ctx)
+
+        if (value === OMIT_SENTINEL) {
+            continue
+        }
+
+        const serializedValue = serializeValue(value, ctx)
+
+        if (serializedValue === OMIT_SENTINEL) {
+            continue
+        }
+
+        result[key] = serializedValue
+    }
+
+    for (const sym of Object.getOwnPropertySymbols(obj)) {
+        const value = safeAccess(obj, sym, onPropertyAccess, ctx)
+
+        if (value === OMIT_SENTINEL) {
+            continue
+        }
+
+        const serializedValue = serializeValue(value, ctx)
+
+        if (serializedValue === OMIT_SENTINEL) {
+            continue
+        }
+
+        result[symbolRegistry(sym)] = serializedValue
+    }
+
+    return result
+}

package/src/serializer/serializers/opaque.ts

@@ -0,0 +1,36 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext } from '../types'
+import { isGenerator } from '../../core'
+import { serializeFunction } from './function'
+
+export function serializeOpaque(value: unknown, ctx: SerializeContext): Jsonable | undefined {
+    if (typeof value === 'function') {
+        return serializeFunction(value as (...args: unknown[]) => unknown, ctx)
+    }
+
+    if (value instanceof Promise) {
+        return ctx.replacer({ type: 'promise', value: '[Promise]' })
+    }
+
+    if (value instanceof WeakMap) {
+        return ctx.replacer({ type: 'weakmap', value: '[WeakMap]' })
+    }
+
+    if (value instanceof WeakSet) {
+        return ctx.replacer({ type: 'weakset', value: '[WeakSet]' })
+    }
+
+    if (typeof WeakRef !== 'undefined' && value instanceof WeakRef) {
+        return ctx.replacer({ type: 'weakref', value: '[WeakRef]' })
+    }
+
+    if (typeof ReadableStream !== 'undefined' && value instanceof ReadableStream) {
+        return ctx.replacer({ type: 'readablestream', value: '[ReadableStream]' })
+    }
+
+    if (isGenerator(value)) {
+        return ctx.replacer({ type: 'generator', value: '[Generator]' })
+    }
+
+    return undefined
+}

package/src/serializer/serializers/primitive.ts

@@ -0,0 +1,32 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext } from '../types'
+import { isBigInt, isJsonablePrimitive, isNumber, isSymbol } from '../../core'
+import { serializeNumber } from './number'
+
+export function serializePrimitive(value: unknown, ctx: SerializeContext): Jsonable | undefined {
+    if (value === null) {
+        return null
+    }
+
+    if (value === undefined) {
+        return ctx.replacer({ type: 'undefined', value: null })
+    }
+
+    if (isNumber(value)) {
+        return serializeNumber(value, ctx)
+    }
+
+    if (isJsonablePrimitive(value)) {
+        return value
+    }
+
+    if (isBigInt(value)) {
+        return ctx.replacer({ type: 'bigint', value: value.toString() })
+    }
+
+    if (isSymbol(value)) {
+        return ctx.replacer({ type: 'symbol', value: ctx.symbolRegistry(value) })
+    }
+
+    return undefined
+}

package/src/serializer/symbol-registry.ts

@@ -0,0 +1,28 @@
+export function createSymbolKeySerializer() {
+    const cache = new Map<symbol, string>()
+    const usedKeys = new Set<string>()
+
+    let counter = 0
+
+    return (symbol: symbol): string => {
+        const cached = cache.get(symbol)
+
+        if (cached !== undefined) {
+            return cached
+        }
+
+        const desc = symbol.description
+        const base = desc?.length ? desc : `@@${++counter}`
+
+        let key = `[Symbol(${base})]`
+
+        while (usedKeys.has(key)) {
+            key = `[Symbol(${base}@@${++counter})]`
+        }
+
+        usedKeys.add(key)
+        cache.set(symbol, key)
+
+        return key
+    }
+}

package/src/serializer/types.ts

@@ -0,0 +1,42 @@
+import type { Jsonable } from '../core'
+import type { OMIT_SENTINEL } from './constants'
+
+export interface SerializedValue {
+    __serialized__: true
+    metadata?: Record<string, Jsonable>
+    type: string
+    value: Jsonable
+}
+
+export type SerializeReplacer = (value: Omit<SerializedValue, '__serialized__'>) => Jsonable
+
+export type SerializeErrorStrategy = 'omit' | 'placeholder' | 'throw'
+
+export interface SerializeErrorHandlers {
+    circularRef?: SerializeErrorStrategy
+    maxDepth?: SerializeErrorStrategy
+    propertyAccess?: SerializeErrorStrategy
+}
+
+export interface SerializeOptions {
+    maxDepth?: number
+    onError?: SerializeErrorHandlers | SerializeErrorStrategy
+    onUnserializable?: ((value: unknown) => Jsonable) | false
+    replacer?: SerializeReplacer
+}
+
+export interface SerializeContext {
+    depth: number
+    readonly maxDepth: number
+    readonly onCircularRef: SerializeErrorStrategy
+    readonly onMaxDepth: SerializeErrorStrategy
+    readonly onPropertyAccess: SerializeErrorStrategy
+    readonly onUnserializable: ((value: unknown) => Jsonable) | false
+    readonly replacer: SerializeReplacer
+    readonly symbolRegistry: (symbol: symbol) => string
+    readonly visited: Set<object>
+}
+
+export type SerializeValueFn = (value: unknown, ctx: SerializeContext) => Jsonable | typeof OMIT_SENTINEL
+
+export type ErrorPropertyValue = Jsonable | typeof OMIT_SENTINEL | undefined

package/src/serializer/utils.ts

@@ -0,0 +1,15 @@
+import type { Jsonable } from '../core'
+import type { SerializeContext, SerializeErrorStrategy } from './types'
+import { OMIT_SENTINEL } from './constants'
+
+export function handleError(strategy: SerializeErrorStrategy, type: string, placeholder: string, ctx: SerializeContext): Jsonable | typeof OMIT_SENTINEL {
+    if (strategy === 'throw') {
+        throw new Error(placeholder)
+    }
+
+    if (strategy === 'omit') {
+        return OMIT_SENTINEL
+    }
+
+    return ctx.replacer({ type, value: placeholder })
+}

package/src/strings/constants.ts

@@ -0,0 +1 @@
+export const WHITESPACE_CHARACTERS = new Set([' ', '\n', '\r', '\t', '\v', '\f'])

package/src/strings/factories.ts

@@ -0,0 +1,9 @@
+export function randomStr(length = 16, characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789') {
+    let result = ''
+
+    for (let i = 0; i < length; i++) {
+        result += characters.charAt(Math.floor(Math.random() * characters.length))
+    }
+
+    return result
+}

package/src/strings/guards.ts

@@ -0,0 +1,51 @@
+import type { Nullish } from '../core'
+import type { HexString, UrlLike } from './types'
+import { wrap } from '../arrays'
+import { transform, tryCatch } from '../functions'
+
+export const isEmptyString = (value: string) => value.length === 0
+
+export function isValidProtocol({ protocol }: URL, protocols?: Nullish<string[]>) {
+    if (!protocols?.length) {
+        return true
+    }
+
+    return protocols.some((x) => `${x.toLowerCase()}:` === protocol)
+}
+
+export function isValidUrl(url: UrlLike, protocols?: Nullish<string[]>) {
+    if (url instanceof URL) {
+        return isValidProtocol(url, protocols)
+    }
+
+    return tryCatch(() => isValidProtocol(new URL(url), protocols), false)
+}
+
+export const isWebSocketUrl = (url: UrlLike, wsProtocols = ['ws', 'wss']) => isValidUrl(url, wsProtocols)
+
+export const isHttpUrl = (url: UrlLike, httpProtocols = ['http', 'https']) => isValidUrl(url, httpProtocols)
+
+export const isStringEquals = (str: string, ...others: string[]) => others.length > 0 && others.every((other) => str === other)
+
+export const isStringEqualsIgnoreCase = (str: string, ...others: string[]) => (
+    others.length > 0 && transform(str.toLowerCase(), (x) => others.every((other) => x === other.toLowerCase()))
+)
+
+export const isIncludesAll = (str: string, search: string[]) => search.every((s) => str.includes(s))
+
+export const isIncludesAny = (str: string, search: string[]) => search.some((s) => str.includes(s))
+
+export const isIncludes = (str: string, search: string[] | string, type: 'all' | 'any' = 'all') => (
+    type === 'all' ? isIncludesAll(str, wrap(search)) : isIncludesAny(str, wrap(search))
+)
+
+export function isHexString(value: string, length?: number) {
+    const len = length ? `{${length * 2}}` : '+'
+    const regex = new RegExp(`^(?:0x)?[0-9a-f]${len}$`, 'iu')
+
+    return regex.test(value)
+}
+
+export const isStrictHexString = (value: string, length?: number): value is HexString => (
+    value.startsWith('0x') && isHexString(value, length)
+)

package/src/strings/index.ts

@@ -0,0 +1,7 @@
+export * from './constants'
+export * from './factories'
+export * from './guards'
+export * from './manipulations'
+export * from './strip-ansi'
+
+export type * from './types'

package/src/strings/manipulations.ts

@@ -0,0 +1,145 @@
+import type { Numberish } from '../numbers'
+import { WHITESPACE_CHARACTERS } from './constants'
+
+export const ensurePrefix = (str: string, prefix: string) => (str.startsWith(prefix) ? str : prefix + str)
+
+export const ensureSuffix = (str: string, suffix: string) => (str.endsWith(suffix) ? str : str + suffix)
+
+export const stripPrefix = (str: string, prefix: string) => (str.startsWith(prefix) ? str.slice(prefix.length) : str)
+
+export const stripSuffix = (str: string, suffix: string) => (suffix.length > 0 && str.endsWith(suffix) ? str.slice(0, -suffix.length) : str)
+
+export const capitalize = (str: string) => str.charAt(0).toUpperCase() + str.slice(1)
+
+export const escapeRegExp = (input: string) => (
+    input.replaceAll(/[$()*+.?[\\\]^{|}]/gu, String.raw`\$&`).replaceAll('-', String.raw`\x2d`)
+)
+
+export function * chunkStr(str: string, size: number) {
+    if (size <= 0) {
+        throw new RangeError(`chunk size must be a positive number, got ${size}`)
+    }
+
+    const len = str.length
+
+    for (let i = 0; i < len; i += size) {
+        yield str.slice(i, i + size)
+    }
+}
+
+export const padStart = (str: string, targetLength: number, padString = ' ') => (
+    str.padStart(targetLength, padString)
+)
+
+export const padZeroStart = (num: Numberish | string, targetLength: number) => padStart(num.toString(), targetLength, '0')
+
+export function truncate(str: string, maxLength: number, omission = '...') {
+    if (str.length <= maxLength) {
+        return str
+    }
+
+    if (omission.length >= maxLength) {
+        return omission.slice(0, maxLength)
+    }
+
+    return str.slice(0, maxLength - omission.length) + omission
+}
+
+export function truncateMiddle(str: string, maxLength: number, omission = '...') {
+    if (str.length <= maxLength) {
+        return str
+    }
+
+    if (omission.length >= maxLength) {
+        return omission.slice(0, maxLength)
+    }
+
+    const left = Math.floor((maxLength - omission.length) / 2)
+    const right = maxLength - omission.length - left
+
+    return str.slice(0, left) + omission + str.slice(-right)
+}
+
+export function ltrim(str: string, characters: Set<string> | string = WHITESPACE_CHARACTERS) {
+    if (typeof characters === 'string') {
+        characters = new Set(characters)
+    }
+
+    const end = str.length
+
+    let start = 0
+
+    while (start < end && characters.has(str[start]!)) {
+        start++
+    }
+
+    return start > 0 ? str.slice(start, end) : str
+}
+
+export function rtrim(str: string, characters: Set<string> | string = WHITESPACE_CHARACTERS) {
+    if (typeof characters === 'string') {
+        characters = new Set(characters)
+    }
+
+    let end = str.length
+
+    while (end > 0 && characters.has(str[end - 1]!)) {
+        end--
+    }
+
+    return end < str.length ? str.slice(0, end) : str
+}
+
+export const trim = (str: string, characters: Set<string> | string = WHITESPACE_CHARACTERS) => (
+    ltrim(rtrim(str, characters), characters)
+)
+
+export const trimRepeated = (input: string, target: string) => (
+    input.replaceAll(new RegExp(`(?:${escapeRegExp(target)}){2,}`, 'g'), target)
+)
+
+export function indent(str: string, count: number, trim = false) {
+    const pad = ' '.repeat(count)
+
+    if (trim) {
+        return str.split('\n').map((line) => pad + ltrim(line)).join('\n')
+    }
+
+    return pad + str.replaceAll('\n', `\n${pad}`)
+}
+
+export function unindent(str: TemplateStringsArray | string, ...values: unknown[]) {
+    const raw = typeof str === 'string' ? str : String.raw({ raw: str }, ...values)
+    const lines = raw.split('\n')
+
+    // Trim leading/trailing empty lines via slice (immutable)
+    let head = 0
+    let tail = lines.length
+
+    while (head < tail && lines[head]!.trim() === '') {
+        head++
+    }
+
+    while (tail > head && lines[tail - 1]!.trim() === '') {
+        tail--
+    }
+
+    const trimmed = lines.slice(head, tail)
+
+    // Find minimum indent across non-empty lines
+    let minIndent = Infinity
+
+    for (const line of trimmed) {
+        if (line.trim() === '') {
+            continue
+        }
+
+        minIndent = Math.min(minIndent, /^[ \t]*/u.exec(line)![0].length)
+    }
+
+    if (minIndent === 0 || minIndent === Infinity) {
+        return trimmed.join('\n')
+    }
+
+    return trimmed.map((line) => line.slice(minIndent)).join('\n')
+}

package/src/strings/strip-ansi.ts

@@ -0,0 +1,14 @@
+// eslint-disable-next-line no-control-regex, regexp/no-control-character, sonarjs/no-control-regex -- ANSI stripping requires matching control characters
+const ANSI_REGEX = /\u001B(?:\[[\d;]*[A-Za-z]|\].*?(?:\u0007|\u001B\\)|\([A-Za-z]|[A-Z])/gu
+
+export function stripAnsi(str: string) {
+    ANSI_REGEX.lastIndex = 0
+
+    if (!ANSI_REGEX.test(str)) {
+        return str
+    }
+
+    ANSI_REGEX.lastIndex = 0
+
+    return str.replace(ANSI_REGEX, '')
+}

package/src/strings/types.ts

@@ -0,0 +1,3 @@
+export type UrlLike = URL | string
+
+export type HexString = `0x${string}`

package/src/system/env.ts

@@ -0,0 +1,32 @@
+import { isUndefined } from '../core'
+
+export const isInMode = (key: string) => process.env.NODE_ENV === key
+
+export const isInDevelopment = () => isInMode('development') || isInMode('dev')
+export const isInDev = isInDevelopment
+
+export const isInProduction = () => isInMode('production') || isInMode('prod')
+export const isInProd = isInProduction
+
+export const isInStaging = () => isInMode('staging') || isInMode('stage')
+export const isInStage = isInStaging
+
+export interface GetEnvOptions {
+    env?: NodeJS.ProcessEnv
+    includeNonePrefix?: boolean
+    prefix?: string
+}
+
+export function getEnv<T extends string>(key: T[], { env = process.env, includeNonePrefix = false, prefix }: GetEnvOptions = {}) {
+    const result: Record<string, string | undefined> = {}
+
+    for (const k of key) {
+        result[k] = env[prefix ? `${prefix}${k}` : k]
+
+        if (includeNonePrefix && isUndefined(result[k])) {
+            result[k] = env[k]
+        }
+    }
+
+    return result as Record<T, string | undefined>
+}

package/src/system/fetch.ts

@@ -0,0 +1,23 @@
+import type { UrlLike } from '../strings'
+import { combineSignals, createAbortController } from '../errors'
+import { resolveOptions } from '../objects'
+import { withRetry, type WithRetryOptions } from '../promises'
+
+export interface FetchOptions extends Omit<RequestInit, 'signal'> {
+    retry?: Omit<WithRetryOptions<Response>, 'signal'> & { enabled?: boolean } | boolean
+    signal?: AbortSignal
+    timeout?: number
+}
+
+export async function fetch(request: RequestInfo | UrlLike, { retry = true, signal, timeout = 10_000, ...options }: FetchOptions = {}) {
+    const retryOptions = { enabled: true, ...(resolveOptions(retry, {}) || { enabled: false }) }
+
+    const execute = async (retrySignal?: AbortSignal) => {
+        const controller = createAbortController(timeout)
+        const fetchSignal = combineSignals(controller.signal, signal, retrySignal)
+
+        return globalThis.fetch(request, { ...options, signal: fetchSignal }).finally(() => controller.abort())
+    }
+
+    return retryOptions.enabled ? await withRetry(execute, { ...retryOptions, signal }) : await execute()
+}

package/src/system/graceful-exit.ts

@@ -0,0 +1,46 @@
+export type ExitHandler = (exitCode?: number) => Promise<void>
+
+const exitTasks = new Map<ExitHandler, number>()
+
+export function addExitHandler(handler: ExitHandler, maxWaitTime = 3000) {
+    exitTasks.set(handler, maxWaitTime)
+
+    return () => {
+        exitTasks.delete(handler)
+    }
+}
+
+let _isExiting = false
+let _exitPromise: Promise<never> | undefined
+
+export const isExiting = () => {
+    return _isExiting
+}
+
+export function gracefulExit(exitCode = 0, maxWaitTime = 3000): Promise<never> {
+    if (_exitPromise) {
+        return _exitPromise
+    }
+
+    _isExiting = true
+
+    if (exitTasks.size === 0) {
+        process.exit(exitCode)
+    }
+
+    const promises: Array<Promise<void>> = []
+
+    for (const [handler, wait] of exitTasks) {
+        promises.push(Promise.resolve().then(() => handler(exitCode)))
+        maxWaitTime = Math.max(maxWaitTime, wait)
+    }
+
+    const timer = setTimeout(() => process.exit(exitCode), maxWaitTime)
+
+    function finish(): never {
+        clearTimeout(timer)
+        process.exit(exitCode)
+    }
+
+    return _exitPromise = Promise.allSettled(promises).then(finish)
+}

package/src/system/index.ts

@@ -0,0 +1,6 @@
+export * from './env'
+export * from './fetch'
+export * from './graceful-exit'
+export * from './path'
+
+export type * from './types'

package/src/system/path.ts

@@ -0,0 +1,12 @@
+import type { PathLike } from './types'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { bufferToString, isBufferLike } from '../buffers'
+
+export const pathToString = (path: PathLike) => (
+    isBufferLike(path) ? bufferToString(path) : path.toString()
+)
+
+export const pwd = (importMeta: ImportMeta, ...path: PathLike[]) => (
+    join(dirname(fileURLToPath(importMeta.url)), ...path.map(pathToString))
+)

package/src/system/types.ts

@@ -0,0 +1,3 @@
+import type { BufferLike } from '../buffers'
+
+export type PathLike = BufferLike | URL | string

package/src/times/constants.ts

@@ -0,0 +1,6 @@
+export const MS_PER_SECOND = 1000
+export const MS_PER_MINUTE = 60_000
+export const MS_PER_HOUR = 3_600_000
+export const MS_PER_DAY = 86_400_000
+export const MS_PER_MONTH = MS_PER_DAY * 30
+export const MS_PER_YEAR = MS_PER_DAY * 365