@kdtlabs/utils 0.0.4 → 0.0.6

package/src/promises/pipe.ts

@@ -0,0 +1,39 @@
+import type { Awaitable } from './types'
+import { isNonEmptyArray } from '../arrays'
+
+export async function pPipe(): Promise<void>
+export async function pPipe<T>(fn: () => Awaitable<T>): Promise<T>
+export async function pPipe<T1, T2>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>): Promise<T2>
+export async function pPipe<T1, T2, T3>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>): Promise<T3>
+export async function pPipe<T1, T2, T3, T4>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>): Promise<T4>
+export async function pPipe<T1, T2, T3, T4, T5>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>): Promise<T5>
+export async function pPipe<T1, T2, T3, T4, T5, T6>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>): Promise<T6>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>): Promise<T7>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>): Promise<T8>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>): Promise<T9>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>): Promise<T10>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>, fn11: (arg: T10) => Awaitable<T11>): Promise<T11>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>, fn11: (arg: T10) => Awaitable<T11>, fn12: (arg: T11) => Awaitable<T12>): Promise<T12>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>, fn11: (arg: T10) => Awaitable<T11>, fn12: (arg: T11) => Awaitable<T12>, fn13: (arg: T12) => Awaitable<T13>): Promise<T13>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>, fn11: (arg: T10) => Awaitable<T11>, fn12: (arg: T11) => Awaitable<T12>, fn13: (arg: T12) => Awaitable<T13>, fn14: (arg: T13) => Awaitable<T14>): Promise<T14>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>, fn11: (arg: T10) => Awaitable<T11>, fn12: (arg: T11) => Awaitable<T12>, fn13: (arg: T12) => Awaitable<T13>, fn14: (arg: T13) => Awaitable<T14>, fn15: (arg: T14) => Awaitable<T15>): Promise<T15>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>, fn11: (arg: T10) => Awaitable<T11>, fn12: (arg: T11) => Awaitable<T12>, fn13: (arg: T12) => Awaitable<T13>, fn14: (arg: T13) => Awaitable<T14>, fn15: (arg: T14) => Awaitable<T15>, fn16: (arg: T15) => Awaitable<T16>): Promise<T16>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>, fn11: (arg: T10) => Awaitable<T11>, fn12: (arg: T11) => Awaitable<T12>, fn13: (arg: T12) => Awaitable<T13>, fn14: (arg: T13) => Awaitable<T14>, fn15: (arg: T14) => Awaitable<T15>, fn16: (arg: T15) => Awaitable<T16>, fn17: (arg: T16) => Awaitable<T17>): Promise<T17>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>, fn11: (arg: T10) => Awaitable<T11>, fn12: (arg: T11) => Awaitable<T12>, fn13: (arg: T12) => Awaitable<T13>, fn14: (arg: T13) => Awaitable<T14>, fn15: (arg: T14) => Awaitable<T15>, fn16: (arg: T15) => Awaitable<T16>, fn17: (arg: T16) => Awaitable<T17>, fn18: (arg: T17) => Awaitable<T18>): Promise<T18>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18, T19>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>, fn11: (arg: T10) => Awaitable<T11>, fn12: (arg: T11) => Awaitable<T12>, fn13: (arg: T12) => Awaitable<T13>, fn14: (arg: T13) => Awaitable<T14>, fn15: (arg: T14) => Awaitable<T15>, fn16: (arg: T15) => Awaitable<T16>, fn17: (arg: T16) => Awaitable<T17>, fn18: (arg: T17) => Awaitable<T18>, fn19: (arg: T18) => Awaitable<T19>): Promise<T19>
+export async function pPipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18, T19, T20>(fn1: () => Awaitable<T1>, fn2: (arg: T1) => Awaitable<T2>, fn3: (arg: T2) => Awaitable<T3>, fn4: (arg: T3) => Awaitable<T4>, fn5: (arg: T4) => Awaitable<T5>, fn6: (arg: T5) => Awaitable<T6>, fn7: (arg: T6) => Awaitable<T7>, fn8: (arg: T7) => Awaitable<T8>, fn9: (arg: T8) => Awaitable<T9>, fn10: (arg: T9) => Awaitable<T10>, fn11: (arg: T10) => Awaitable<T11>, fn12: (arg: T11) => Awaitable<T12>, fn13: (arg: T12) => Awaitable<T13>, fn14: (arg: T13) => Awaitable<T14>, fn15: (arg: T14) => Awaitable<T15>, fn16: (arg: T15) => Awaitable<T16>, fn17: (arg: T16) => Awaitable<T17>, fn18: (arg: T17) => Awaitable<T18>, fn19: (arg: T18) => Awaitable<T19>, fn20: (arg: T19) => Awaitable<T20>): Promise<T20>
+export async function pPipe(...fns: CallableFunction[]): Promise<unknown>
+
+export async function pPipe(...fns: CallableFunction[]) {
+    if (!isNonEmptyArray(fns)) {
+        return
+    }
+
+    let result = await fns[0]()
+
+    for (let i = 1; i < fns.length; i++) {
+        result = await fns[i]!(result)
+    }
+
+    return result
+}

package/src/promises/poll.ts

@@ -0,0 +1,92 @@
+import type { Awaitable } from './types'
+import { assertParam } from '../common'
+import { createAbortController, isAbortError } from '../errors'
+import { isFunction } from '../functions'
+import { isPlainObject } from '../objects'
+import { abortable } from './abortable'
+import { sleep } from './timers'
+
+export interface PollOptions {
+    delay?: number
+    immediately?: boolean
+    onError?: (error: unknown) => void
+    stopOnError?: boolean
+}
+
+export type PollFn = (signal: AbortSignal) => Awaitable<void>
+
+export function poll(fn: PollFn, options?: PollOptions): () => Promise<void>
+export function poll(options: PollOptions, fn: PollFn): () => Promise<void>
+
+export function poll(fnOrOptions: PollFn | PollOptions, optionsOrFn: PollFn | PollOptions = {}) {
+    let fn: PollFn
+    let options: PollOptions
+
+    if (isFunction(fnOrOptions) && isPlainObject(optionsOrFn)) {
+        fn = fnOrOptions
+        options = optionsOrFn
+    } else {
+        assertParam(isPlainObject(fnOrOptions), 'options must be an object')
+        assertParam(isFunction(optionsOrFn), 'fn must be a function')
+
+        fn = optionsOrFn
+        options = fnOrOptions
+    }
+
+    const { delay = 0, immediately = true, onError, stopOnError = true } = options
+    const abortController = createAbortController()
+
+    let isActive = true
+    let currentTask: Promise<void> | undefined
+
+    const stop = () => {
+        isActive = false
+        abortController.abort()
+
+        return currentTask ?? Promise.resolve()
+    }
+
+    let startRun: () => void
+
+    const run = async () => {
+        if (!isActive) {
+            return
+        }
+
+        try {
+            await abortable(Promise.resolve(fn(abortController.signal)), abortController.signal)
+
+            if (isActive) {
+                await sleep(delay, { signal: abortController.signal })
+            }
+        } catch (error) {
+            if (isAbortError(error) && !isActive) {
+                return
+            }
+
+            onError?.(error)
+
+            if (stopOnError) {
+                stop()
+
+                return
+            }
+        }
+
+        setTimeout(startRun, 0)
+    }
+
+    startRun = () => {
+        currentTask = run().finally(() => {
+            currentTask = undefined
+        })
+    }
+
+    if (immediately) {
+        Promise.resolve().then(startRun)
+    } else {
+        setTimeout(startRun, delay)
+    }
+
+    return stop
+}

package/src/promises/retry.ts

@@ -0,0 +1,138 @@
+import type { Awaitable } from './types'
+import { isAbortError } from '../errors'
+import { clamp } from '../numbers'
+import { abortable } from './abortable'
+import { sleep } from './timers'
+
+export interface GetRetryDelayOptions {
+    backoff?: number
+    delay?: number
+    jitter?: number
+    maxDelay?: number
+}
+
+export function getRetryDelay(attempts: number, { backoff = 2, delay = 1000, jitter = 0.01, maxDelay = 10_000 }: GetRetryDelayOptions = {}) {
+    const exponentialDelay = delay * backoff ** (attempts - 1)
+    const clampedDelay = clamp(exponentialDelay, 0, maxDelay)
+
+    if (jitter <= 0) {
+        return clampedDelay
+    }
+
+    const jitterRange = clampedDelay * jitter
+    const jitterOffset = (Math.random() - 0.5) * 2 * jitterRange
+
+    return clamp(clampedDelay + jitterOffset, 0, maxDelay)
+}
+
+export interface WithRetryContext {
+    attempts: number
+    retriesLeft: number
+    signal?: AbortSignal
+}
+
+export interface WithRetryOptions<T> extends GetRetryDelayOptions {
+    maxAttempts?: number
+    onBeforeWaitForNextAttempt?: (delay: number, context: WithRetryContext) => Awaitable<void>
+    onFailedAttempt?: (error: unknown, context: WithRetryContext) => Awaitable<void>
+    onSuccessAttempt?: (response: T, context: WithRetryContext) => Awaitable<void>
+    shouldRetry?: (error: unknown, context: WithRetryContext) => Awaitable<boolean>
+    shouldRetryOnSuccess?: (result: T, context: WithRetryContext) => Awaitable<boolean>
+    signal?: AbortSignal
+}
+
+export function createRetryError(errors: unknown[]) {
+    if (errors.length === 1) {
+        return errors[0]
+    }
+
+    return new AggregateError(errors, 'All retry attempts failed')
+}
+
+export function rethrowNonAbortError(error: unknown) {
+    if (!isAbortError(error)) {
+        throw error
+    }
+}
+
+export async function waitForNextRetryAttempt(attempts: number, delayOptions: GetRetryDelayOptions, onBeforeWaitForNextAttempt: WithRetryOptions<unknown>['onBeforeWaitForNextAttempt'], signal: AbortSignal | undefined, context: WithRetryContext) {
+    const delay = getRetryDelay(attempts, delayOptions)
+
+    await onBeforeWaitForNextAttempt?.(delay, context)
+    await sleep(delay, { signal }).catch(rethrowNonAbortError)
+}
+
+export async function handleRetryFailure<T>(error: unknown, errors: unknown[], retriesLeft: number, shouldRetry: WithRetryOptions<T>['shouldRetry'], onFailedAttempt: WithRetryOptions<T>['onFailedAttempt'], context: WithRetryContext) {
+    if (isAbortError(error)) {
+        throw error
+    }
+
+    errors.push(error)
+
+    if (retriesLeft <= 0) {
+        throw createRetryError(errors)
+    }
+
+    if (shouldRetry && !(await shouldRetry(error, context))) {
+        throw createRetryError(errors)
+    }
+
+    await onFailedAttempt?.(error, context)
+}
+
+export async function handleRetrySuccess<T>(result: T, errors: unknown[], retriesLeft: number, shouldRetryOnSuccess: WithRetryOptions<T>['shouldRetryOnSuccess'], onSuccessAttempt: WithRetryOptions<T>['onSuccessAttempt'], context: WithRetryContext): Promise<boolean> {
+    if (!shouldRetryOnSuccess || !(await shouldRetryOnSuccess(result, context))) {
+        return true
+    }
+
+    if (retriesLeft <= 0) {
+        throw createRetryError(errors)
+    }
+
+    await onSuccessAttempt?.(result, context)
+
+    return false
+}
+
+export async function withRetry<T>(fn: (signal?: AbortSignal) => Awaitable<T>, { maxAttempts = 3, onBeforeWaitForNextAttempt, onFailedAttempt, onSuccessAttempt, shouldRetry, shouldRetryOnSuccess, signal, ...delayOptions }: WithRetryOptions<T> = {}): Promise<T> {
+    if (maxAttempts < 1) {
+        throw new RangeError('maxAttempts must be at least 1')
+    }
+
+    if (signal) {
+        signal.throwIfAborted()
+    }
+
+    let attempts = 0
+    let result: T
+
+    const errors: unknown[] = []
+
+    while (attempts < maxAttempts) {
+        const retriesLeft = maxAttempts - ((attempts++) + 1)
+        const context = { attempts, retriesLeft, signal }
+
+        try {
+            if (signal) {
+                signal.throwIfAborted()
+            }
+
+            result = await abortable(Promise.resolve(fn(signal)), signal)
+        } catch (error) {
+            await handleRetryFailure(error, errors, retriesLeft, shouldRetry, onFailedAttempt, context)
+            await waitForNextRetryAttempt(attempts, delayOptions, onBeforeWaitForNextAttempt, signal, context)
+
+            continue
+        }
+
+        const shouldReturn = await handleRetrySuccess(result, errors, retriesLeft, shouldRetryOnSuccess, onSuccessAttempt, context)
+
+        if (shouldReturn) {
+            return result
+        }
+
+        await waitForNextRetryAttempt(attempts, delayOptions, onBeforeWaitForNextAttempt, signal, context)
+    }
+
+    throw createRetryError(errors)
+}

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'