@kdtlabs/utils 0.0.4 → 0.0.5

package/src/promises/timers.ts

@@ -0,0 +1,16 @@
+import { combineSignals, createAbortController, type Errorable } from '../errors'
+import { transform } from '../functions'
+import { abortable } from './abortable'
+
+export interface TimerOptions {
+    error?: Errorable
+    signal?: AbortSignal
+}
+
+export const sleep = async (ms: number, { error, signal }: TimerOptions = {}) => (
+    abortable(new Promise<void>((resolve) => setTimeout(resolve, ms)), signal, error)
+)
+
+export const withTimeout = <T>(promise: Promise<T>, ms: number, { error, signal }: TimerOptions = {}) => (
+    transform(createAbortController(ms, error), (controller) => abortable(promise, combineSignals(signal, controller.signal)).finally(() => controller.abort()))
+)

package/src/promises/types.ts

@@ -0,0 +1 @@
+export type Awaitable<T> = PromiseLike<T> | T

package/src/serializer/constants.ts

@@ -0,0 +1,5 @@
+export const SERIALIZE = Symbol.for('serialize.custom')
+
+export const GENERATOR_PATTERNS = /\bfunction\s*\*|^async\s+function\s*\*|\*\s*\[|^\*\s/u
+
+export const OMIT_SENTINEL = Symbol('omit')

package/src/serializer/context.ts

@@ -0,0 +1,24 @@
+import type { Jsonable } from '../core'
+import type { SerializeContext, SerializedValue, SerializeErrorStrategy, SerializeOptions } from './types'
+import { createSymbolKeySerializer } from './symbol-registry'
+
+export const DEFAULT_REPLACER = (value: Omit<SerializedValue, '__serialized__'>): Jsonable => ({ ...value, __serialized__: true }) as Jsonable
+
+export function createContext(options: SerializeOptions = {}): SerializeContext {
+    const { maxDepth = Number.POSITIVE_INFINITY, onUnserializable = false, replacer = DEFAULT_REPLACER } = options
+    let onCircularRef: SerializeErrorStrategy = 'placeholder'
+    let onMaxDepth: SerializeErrorStrategy = 'placeholder'
+    let onPropertyAccess: SerializeErrorStrategy = 'placeholder'
+
+    if (typeof options.onError === 'string') {
+        onCircularRef = options.onError
+        onMaxDepth = options.onError
+        onPropertyAccess = options.onError
+    } else if (typeof options.onError === 'object' && options.onError != null) {
+        onCircularRef = options.onError.circularRef ?? 'placeholder'
+        onMaxDepth = options.onError.maxDepth ?? 'placeholder'
+        onPropertyAccess = options.onError.propertyAccess ?? 'placeholder'
+    }
+
+    return { depth: 0, maxDepth, onCircularRef, onMaxDepth, onPropertyAccess, onUnserializable, replacer, symbolRegistry: createSymbolKeySerializer(), visited: new Set() }
+}

package/src/serializer/index.ts

@@ -0,0 +1,8 @@
+export * from './constants'
+export * from './context'
+export * from './serialize'
+export * from './serializers'
+export * from './symbol-registry'
+export * from './utils'
+
+export type * from './types'

package/src/serializer/serialize.ts

@@ -0,0 +1,51 @@
+import type { Jsonable } from '../core'
+import type { SerializeContext, SerializeOptions } from './types'
+import { OMIT_SENTINEL } from './constants'
+import { createContext } from './context'
+import { serializeCompound } from './serializers/compound'
+import { serializeLeafObject } from './serializers/leaf-object'
+import { serializePrimitive } from './serializers/primitive'
+import { handleError } from './utils'
+
+export function serialize(value: unknown, options?: SerializeOptions): Jsonable {
+    const ctx = createContext(options)
+    const serializedValue = serializeValue(value, ctx)
+
+    if (serializedValue === OMIT_SENTINEL) {
+        return null
+    }
+
+    return serializedValue
+}
+
+export function serializeValue(value: unknown, ctx: SerializeContext): Jsonable | typeof OMIT_SENTINEL {
+    const primitive = serializePrimitive(value, ctx)
+
+    if (primitive !== undefined) {
+        return primitive
+    }
+
+    const leaf = serializeLeafObject(value, ctx)
+
+    if (leaf !== undefined) {
+        return leaf
+    }
+
+    if (ctx.visited.has(value as object)) {
+        return handleError(ctx.onCircularRef, 'circular-ref', '[Circular]', ctx)
+    }
+
+    if (ctx.depth >= ctx.maxDepth) {
+        return handleError(ctx.onMaxDepth, 'max-depth', '[Max Depth]', ctx)
+    }
+
+    ctx.visited.add(value as object)
+    ctx.depth++
+
+    try {
+        return serializeCompound(value as object, ctx, serializeValue)
+    } finally {
+        ctx.depth--
+        ctx.visited.delete(value as object)
+    }
+}

package/src/serializer/serializers/array.ts

@@ -0,0 +1,17 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext, SerializeValueFn } from '../types'
+import { OMIT_SENTINEL } from '../constants'
+
+export function serializeArrayEntry(entry: unknown, ctx: SerializeContext, serializeValue: SerializeValueFn): Jsonable {
+    const serializedValue = serializeValue(entry, ctx)
+
+    return serializedValue === OMIT_SENTINEL ? null : serializedValue
+}
+
+export const serializeArray = (value: unknown[], ctx: SerializeContext, serializeValue: SerializeValueFn): Jsonable[] => (
+    value.map((entry) => serializeArrayEntry(entry, ctx, serializeValue))
+)
+
+export const serializeIterableEntries = (value: Iterable<unknown>, ctx: SerializeContext, serializeValue: SerializeValueFn): Jsonable[] => (
+    Array.from(value, (entry) => serializeArrayEntry(entry, ctx, serializeValue))
+)

package/src/serializer/serializers/binary.ts

@@ -0,0 +1,24 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext } from '../types'
+
+export function serializeBinary(value: object, ctx: SerializeContext): Jsonable | undefined {
+    if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+        const typed = value as unknown as { [Symbol.toStringTag]: string, byteLength: number, byteOffset: number, length: number }
+
+        return ctx.replacer({
+            metadata: { byteLength: typed.byteLength, byteOffset: typed.byteOffset },
+            type: typed[Symbol.toStringTag]?.toLowerCase() ?? 'typedarray',
+            value: Array.from({ length: typed.length }, (_, index) => (value as unknown as ArrayLike<number>)[index]!),
+        })
+    }
+
+    if (value instanceof ArrayBuffer || (typeof SharedArrayBuffer !== 'undefined' && value instanceof SharedArrayBuffer)) {
+        return ctx.replacer({ metadata: { byteLength: value.byteLength }, type: 'arraybuffer', value: [...new Uint8Array(value)] })
+    }
+
+    if (value instanceof DataView) {
+        return ctx.replacer({ metadata: { byteLength: value.byteLength, byteOffset: value.byteOffset }, type: 'dataview', value: null })
+    }
+
+    return undefined
+}

package/src/serializer/serializers/blob.ts

@@ -0,0 +1,18 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext } from '../types'
+
+export function serializeBlob(value: object, ctx: SerializeContext): Jsonable | undefined {
+    if (typeof Blob === 'undefined' || !(value instanceof Blob)) {
+        return undefined
+    }
+
+    const metadata: Record<string, Jsonable> = { size: value.size, type: value.type }
+
+    if (typeof File !== 'undefined' && value instanceof File) {
+        metadata.name = value.name
+
+        return ctx.replacer({ metadata, type: 'file', value: null })
+    }
+
+    return ctx.replacer({ metadata, type: 'blob', value: null })
+}

package/src/serializer/serializers/collection.ts

@@ -0,0 +1,25 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext, SerializeValueFn } from '../types'
+import { isCollectionLike, isMapLike, isSetLike } from '../../collections'
+import { serializeIterableEntries } from './array'
+
+export function serializeCollection(value: object, ctx: SerializeContext, serializeValue: SerializeValueFn): Jsonable | undefined {
+    if (isCollectionLike(value)) {
+        const name = value.constructor?.name
+        const metadata: Record<string, Jsonable> = { size: value.size }
+
+        if (name) {
+            metadata.name = name
+        }
+
+        if (isMapLike(value)) {
+            return ctx.replacer({ metadata, type: 'map', value: serializeIterableEntries(value.entries(), ctx, serializeValue) })
+        }
+
+        if (isSetLike(value)) {
+            return ctx.replacer({ metadata, type: 'set', value: serializeIterableEntries(value, ctx, serializeValue) })
+        }
+    }
+
+    return undefined
+}

package/src/serializer/serializers/compound.ts

@@ -0,0 +1,79 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext, SerializeValueFn } from '../types'
+import { isArray } from '../../arrays'
+import { isIterable } from '../../collections'
+import { typeOf } from '../../core'
+import { isPlainObject } from '../../objects'
+import { type OMIT_SENTINEL, SERIALIZE } from '../constants'
+import { serializeArray, serializeIterableEntries } from './array'
+import { serializeBinary } from './binary'
+import { serializeBlob } from './blob'
+import { serializeCollection } from './collection'
+import { serializeError } from './error'
+import { serializeObject } from './object'
+import { serializeOpaque } from './opaque'
+
+export function serializeCompound(value: object, ctx: SerializeContext, serializeValue: SerializeValueFn): Jsonable | typeof OMIT_SENTINEL {
+    const customSerialize = (value as Record<PropertyKey, unknown>)[SERIALIZE]
+
+    if (typeof customSerialize === 'function') {
+        return serializeValue((customSerialize as () => unknown)(), ctx)
+    }
+
+    if (isArray(value)) {
+        return serializeArray(value, ctx, serializeValue)
+    }
+
+    const collection = serializeCollection(value, ctx, serializeValue)
+
+    if (collection !== undefined) {
+        return collection
+    }
+
+    const binary = serializeBinary(value, ctx)
+
+    if (binary !== undefined) {
+        return binary
+    }
+
+    const blob = serializeBlob(value, ctx)
+
+    if (blob !== undefined) {
+        return blob
+    }
+
+    if (value instanceof Error) {
+        return ctx.replacer({ type: 'error', value: serializeError(value, ctx, serializeValue) })
+    }
+
+    if (isPlainObject(value)) {
+        return serializeObject(value, ctx, serializeValue)
+    }
+
+    const opaque = serializeOpaque(value, ctx)
+
+    if (opaque !== undefined) {
+        return opaque
+    }
+
+    if (typeof (value as Record<string, unknown>).toJSON === 'function') {
+        return serializeValue((value as { toJSON: () => unknown }).toJSON(), ctx)
+    }
+
+    if (isIterable(value)) {
+        const name = value.constructor?.name
+        const metadata: Record<string, Jsonable> = {}
+
+        if (name) {
+            metadata.name = name
+        }
+
+        return ctx.replacer({ metadata, type: 'iterable', value: serializeIterableEntries(value, ctx, serializeValue) })
+    }
+
+    if (ctx.onUnserializable) {
+        return ctx.onUnserializable(value)
+    }
+
+    return ctx.replacer({ type: typeOf(value), value: `[${value.constructor?.name ?? typeOf(value)}]` })
+}

package/src/serializer/serializers/error.ts

@@ -0,0 +1,75 @@
+import type { Jsonable } from '../../core'
+import type { ErrorPropertyValue, SerializeContext, SerializeValueFn } from '../types'
+import { OMIT_SENTINEL } from '../constants'
+import { handlePropertyAccessError } from './object'
+
+export const isUsableValue = (value: ErrorPropertyValue): value is Jsonable => (
+    value !== undefined && value !== OMIT_SENTINEL
+)
+
+export function readProperty(error: Error, key: string | symbol, ctx: SerializeContext, serializeValue: SerializeValueFn): ErrorPropertyValue {
+    try {
+        const value = (error as unknown as Record<string | symbol, unknown>)[key]
+
+        if (value === undefined) {
+            return undefined
+        }
+
+        return serializeValue(value, ctx)
+    } catch (error_) {
+        return handlePropertyAccessError(error_, ctx.onPropertyAccess, key, ctx)
+    }
+}
+
+export function serializeErrorCoreFields(error: Error, ctx: SerializeContext, serializeValue: SerializeValueFn): Record<string, Jsonable> {
+    const result: Record<string, Jsonable> = { name: error.name }
+    const serializedMessage = readProperty(error, 'message', ctx, serializeValue)
+    const serializedStack = readProperty(error, 'stack', ctx, serializeValue)
+    const serializedCause = readProperty(error, 'cause', ctx, serializeValue)
+
+    if (typeof serializedMessage === 'string' && serializedMessage.length > 0) {
+        result.message = serializedMessage
+    }
+
+    if (typeof serializedStack === 'string' && serializedStack.length > 0) {
+        result.stack = serializedStack
+    }
+
+    if (isUsableValue(serializedCause)) {
+        result.cause = serializedCause
+    }
+
+    if (error instanceof AggregateError) {
+        const serializedErrors = readProperty(error, 'errors', ctx, serializeValue)
+
+        if (isUsableValue(serializedErrors)) {
+            result.errors = serializedErrors
+        }
+    }
+
+    return result
+}
+
+export function serializeError(error: Error, ctx: SerializeContext, serializeValue: SerializeValueFn): Record<string, Jsonable> {
+    const result = serializeErrorCoreFields(error, ctx, serializeValue)
+
+    for (const key of Object.keys(error)) {
+        if (!(key in result)) {
+            const serializedValue = readProperty(error, key, ctx, serializeValue)
+
+            if (isUsableValue(serializedValue)) {
+                result[key] = serializedValue
+            }
+        }
+    }
+
+    for (const sym of Object.getOwnPropertySymbols(error)) {
+        const serializedValue = readProperty(error, sym, ctx, serializeValue)
+
+        if (isUsableValue(serializedValue)) {
+            result[ctx.symbolRegistry(sym)] = serializedValue
+        }
+    }
+
+    return result
+}

package/src/serializer/serializers/function.ts

@@ -0,0 +1,13 @@
+import type { Jsonable } from '../../core'
+import type { SerializeContext } from '../types'
+import { GENERATOR_PATTERNS } from '../constants'
+
+export function serializeFunction(fn: (...args: unknown[]) => unknown, ctx: SerializeContext): Jsonable {
+    const metadata: Record<string, Jsonable> = {}
+    const str = fn.toString()
+
+    metadata.async = str.startsWith('async')
+    metadata.generator = GENERATOR_PATTERNS.test(str)
+
+    return ctx.replacer({ metadata, type: 'function', value: { length: fn.length, name: fn.name || 'anonymous' } })
+}

package/src/serializer/serializers/index.ts

@@ -0,0 +1,12 @@
+export * from './array'
+export * from './binary'
+export * from './blob'
+export * from './collection'
+export * from './compound'
+export * from './error'
+export * from './function'
+export * from './leaf-object'
+export * from './number'
+export * from './object'
+export * from './opaque'
+export * from './primitive'

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
+}