@bgskinner2/ts-utils 1.0.0 → 1.0.2

package/dist/index.d.cts

@@ -1,10 +1,5 @@
 import * as react from 'react';
-import { ElementType, ComponentPropsWithoutRef, ReactElement, MouseEvent, ReactNode, ComponentType, ForwardRefExoticComponent, ReactPortal, Ref, RefObject } from 'react';
-
-/**  @see {@link TypeDocs.TStaticMethods}  */
-type TStaticMethods<T> = {
-    [K in keyof T as T[K] extends (...args: any) => any ? K : never]: T[K];
-};
+import { ElementType, ComponentPropsWithoutRef, ReactElement, MouseEvent, ReactNode, ComponentType, ForwardRefExoticComponent, ReactPortal, Ref, RefObject, CSSProperties, SyntheticEvent, RefCallback } from 'react';
 
 type TArrayLengthMutationKeys = 'splice' | 'push' | 'pop' | 'shift' | 'unshift' | number;
 type TArrayItems<T extends Array<unknown>> = T extends Array<infer TItems> ? TItems : never;
@@ -61,29 +56,6 @@ type CamelCaseFromArray<WordsArr extends string[], Options extends {
 ] ? Options['preserveConsecutiveUppercase'] extends true ? `${Capitalize<FirstWord>}${CamelCaseFromArray<Rest, Options>}` : `${Capitalize<Lowercase<FirstWord>>}${CamelCaseFromArray<Rest, Options>}` : OutputString;
 type TCamelCase<Type, Options extends TDelimiterCaseOptions = object> = Type extends string ? string extends Type ? Type : Uncapitalize<CamelCaseFromArray<TWords<Type extends Uppercase<Type> ? Lowercase<Type> : Type>, TMergeDelimiterCaseOptions<Options>>> : Type;
 
-declare const LOG_TYPES: readonly ["log", "warn", "error", "info", "debug", "table"];
-declare const REGEX_CONSTANTS: {
-    readonly isoRegex: RegExp;
-    readonly camelCase: RegExp;
-    readonly kebabCase: RegExp;
-    readonly snakeCase: RegExp;
-    readonly hexString: RegExp;
-    readonly hexColor: RegExp;
-    readonly letterSeparator: RegExp;
-    readonly camelCaseBoundary: RegExp;
-    readonly kebabCaseBoundary: RegExp;
-    readonly whitespace: RegExp;
-    readonly wordBoundarySplitter: RegExp;
-    readonly USPhoneNumber: RegExp;
-    readonly EUPhoneNumber: RegExp;
-    readonly genericPhoneNumber: RegExp;
-    readonly genericEmail: RegExp;
-    readonly emailRegex: RegExp;
-    readonly imageSrcRegex: RegExp;
-    readonly singleAlphabetChar: RegExp;
-    readonly htmlDetection: RegExp;
-    readonly stackTracePrefix: RegExp;
-};
 declare const ANSI_COLOR_CODES: {
     readonly reset: "\u001B[0m";
     readonly black: "\u001B[30m";
@@ -98,426 +70,7 @@ declare const ANSI_COLOR_CODES: {
     readonly underline: "\u001B[4m";
 };
 
-declare const VALID_DOM_PROPS: {
-    abbr: true;
-    accept: true;
-    acceptCharset: true;
-    accessKey: true;
-    action: true;
-    allow: true;
-    allowFullScreen: true;
-    allowPaymentRequest: true;
-    alt: true;
-    async: true;
-    autoComplete: true;
-    autoFocus: true;
-    autoPlay: true;
-    capture: true;
-    cellPadding: true;
-    cellSpacing: true;
-    challenge: true;
-    charSet: true;
-    checked: true;
-    cite: true;
-    classID: true;
-    className: true;
-    cols: true;
-    colSpan: true;
-    content: true;
-    contentEditable: true;
-    contextMenu: true;
-    controls: true;
-    controlsList: true;
-    coords: true;
-    crossOrigin: true;
-    data: true;
-    dateTime: true;
-    decoding: true;
-    default: true;
-    defer: true;
-    dir: true;
-    disabled: true;
-    disablePictureInPicture: true;
-    disableRemotePlayback: true;
-    download: true;
-    draggable: true;
-    encType: true;
-    enterKeyHint: true;
-    form: true;
-    formAction: true;
-    formEncType: true;
-    formMethod: true;
-    formNoValidate: true;
-    formTarget: true;
-    frameBorder: true;
-    headers: true;
-    height: true;
-    hidden: true;
-    high: true;
-    href: true;
-    hrefLang: true;
-    htmlFor: true;
-    httpEquiv: true;
-    id: true;
-    inputMode: true;
-    integrity: true;
-    is: true;
-    keyParams: true;
-    keyType: true;
-    kind: true;
-    label: true;
-    lang: true;
-    list: true;
-    loading: true;
-    loop: true;
-    low: true;
-    marginHeight: true;
-    marginWidth: true;
-    max: true;
-    maxLength: true;
-    media: true;
-    mediaGroup: true;
-    method: true;
-    min: true;
-    minLength: true;
-    multiple: true;
-    muted: true;
-    name: true;
-    nonce: true;
-    noValidate: true;
-    open: true;
-    optimum: true;
-    pattern: true;
-    placeholder: true;
-    playsInline: true;
-    poster: true;
-    preload: true;
-    profile: true;
-    radioGroup: true;
-    readOnly: true;
-    referrerPolicy: true;
-    rel: true;
-    required: true;
-    reversed: true;
-    role: true;
-    rows: true;
-    rowSpan: true;
-    sandbox: true;
-    scope: true;
-    scoped: true;
-    scrolling: true;
-    seamless: true;
-    selected: true;
-    shape: true;
-    size: true;
-    sizes: true;
-    slot: true;
-    span: true;
-    spellCheck: true;
-    src: true;
-    srcDoc: true;
-    srcLang: true;
-    srcSet: true;
-    start: true;
-    step: true;
-    style: true;
-    summary: true;
-    tabIndex: true;
-    target: true;
-    title: true;
-    translate: true;
-    type: true;
-    useMap: true;
-    value: true;
-    width: true;
-    wmode: true;
-    wrap: true;
-    alignmentBaseline: true;
-    baselineShift: true;
-    clip: true;
-    clipPath: true;
-    clipRule: true;
-    color: true;
-    colorInterpolation: true;
-    colorInterpolationFilters: true;
-    colorProfile: true;
-    colorRendering: true;
-    cursor: true;
-    direction: true;
-    display: true;
-    dominantBaseline: true;
-    enableBackground: true;
-    fill: true;
-    fillOpacity: true;
-    fillRule: true;
-    filter: true;
-    floodColor: true;
-    floodOpacity: true;
-    imageRendering: true;
-    lightingColor: true;
-    markerEnd: true;
-    markerMid: true;
-    markerStart: true;
-    mask: true;
-    opacity: true;
-    overflow: true;
-    paintOrder: true;
-    pointerEvents: true;
-    shapeRendering: true;
-    stopColor: true;
-    stopOpacity: true;
-    stroke: true;
-    strokeDasharray: true;
-    strokeDashoffset: true;
-    strokeLinecap: true;
-    strokeLinejoin: true;
-    strokeMiterlimit: true;
-    strokeOpacity: true;
-    strokeWidth: true;
-    textAnchor: true;
-    textDecoration: true;
-    textRendering: true;
-    unicodeBidi: true;
-    vectorEffect: true;
-    visibility: true;
-    wordSpacing: true;
-    writingMode: true;
-    cx: true;
-    cy: true;
-    d: true;
-    dx: true;
-    dy: true;
-    fr: true;
-    fx: true;
-    fy: true;
-    points: true;
-    r: true;
-    rx: true;
-    ry: true;
-    transform: true;
-    version: true;
-    viewBox: true;
-    x: true;
-    x1: true;
-    x2: true;
-    y: true;
-    y1: true;
-    y2: true;
-    z: true;
-    accumulate: true;
-    additive: true;
-    allowReorder: true;
-    amplitude: true;
-    attributeName: true;
-    attributeType: true;
-    autoReverse: true;
-    begin: true;
-    bias: true;
-    by: true;
-    calcMode: true;
-    decelerate: true;
-    diffuseConstant: true;
-    divisor: true;
-    dur: true;
-    edgeMode: true;
-    elevation: true;
-    end: true;
-    exponent: true;
-    externalResourcesRequired: true;
-    filterRes: true;
-    filterUnits: true;
-    from: true;
-    in: true;
-    in2: true;
-    intercept: true;
-    k: true;
-    k1: true;
-    k2: true;
-    k3: true;
-    k4: true;
-    kernelMatrix: true;
-    kernelUnitLength: true;
-    keyPoints: true;
-    keySplines: true;
-    keyTimes: true;
-    limitingConeAngle: true;
-    mode: true;
-    numOctaves: true;
-    operator: true;
-    order: true;
-    orient: true;
-    orientation: true;
-    origin: true;
-    pathLength: true;
-    primitiveUnits: true;
-    repeatCount: true;
-    repeatDur: true;
-    restart: true;
-    result: true;
-    rotate: true;
-    scale: true;
-    seed: true;
-    slope: true;
-    spacing: true;
-    specularConstant: true;
-    specularExponent: true;
-    speed: true;
-    spreadMethod: true;
-    startOffset: true;
-    stdDeviation: true;
-    stitchTiles: true;
-    surfaceScale: true;
-    targetX: true;
-    targetY: true;
-    to: true;
-    values: true;
-    xChannelSelector: true;
-    yChannelSelector: true;
-    zoomAndPan: true;
-    accentHeight: true;
-    alphabetic: true;
-    arabicForm: true;
-    ascent: true;
-    bbox: true;
-    capHeight: true;
-    descent: true;
-    fontFamily: true;
-    fontSize: true;
-    fontSizeAdjust: true;
-    fontStretch: true;
-    fontStyle: true;
-    fontVariant: true;
-    fontWeight: true;
-    format: true;
-    g1: true;
-    g2: true;
-    glyphName: true;
-    glyphOrientationHorizontal: true;
-    glyphOrientationVertical: true;
-    glyphRef: true;
-    hanging: true;
-    horizAdvX: true;
-    horizOriginX: true;
-    ideographic: true;
-    kerning: true;
-    lengthAdjust: true;
-    letterSpacing: true;
-    local: true;
-    mathematical: true;
-    overlinePosition: true;
-    overlineThickness: true;
-    panose1: true;
-    refX: true;
-    refY: true;
-    renderingIntent: true;
-    strikethroughPosition: true;
-    strikethroughThickness: true;
-    string: true;
-    systemLanguage: true;
-    tableValues: true;
-    textLength: true;
-    u1: true;
-    u2: true;
-    underlinePosition: true;
-    underlineThickness: true;
-    unicode: true;
-    unicodeRange: true;
-    unitsPerEm: true;
-    vAlphabetic: true;
-    vHanging: true;
-    vIdeographic: true;
-    vMathematical: true;
-    vertAdvY: true;
-    vertOriginX: true;
-    vertOriginY: true;
-    widths: true;
-    xHeight: true;
-    clipPathUnits: true;
-    contentScriptType: true;
-    contentStyleType: true;
-    gradientTransform: true;
-    gradientUnits: true;
-    markerHeight: true;
-    markerUnits: true;
-    markerWidth: true;
-    maskContentUnits: true;
-    maskUnits: true;
-    offset: true;
-    patternContentUnits: true;
-    patternTransform: true;
-    patternUnits: true;
-    preserveAlpha: true;
-    preserveAspectRatio: true;
-    requiredExtensions: true;
-    requiredFeatures: true;
-    viewTarget: true;
-    xlinkActuate: true;
-    xlinkArcrole: true;
-    xlinkHref: true;
-    xlinkRole: true;
-    xlinkShow: true;
-    xlinkTitle: true;
-    xlinkType: true;
-    xmlBase: true;
-    xmlns: true;
-    xmlnsXlink: true;
-    xmlLang: true;
-    xmlSpace: true;
-    for: true;
-    class: true;
-    autofocus: true;
-    children: true;
-    dangerouslySetInnerHTML: true;
-    key: true;
-    ref: true;
-    defaultValue: true;
-    defaultChecked: true;
-    innerHTML: true;
-    suppressContentEditableWarning: true;
-    suppressHydrationWarning: true;
-    valueLink: true;
-    onCaptured: true;
-    precedence: true;
-    blocking: true;
-    autoCorrect: true;
-    autoCapitalize: true;
-    popover: true;
-    popoverTarget: true;
-    popoverTargetAction: true;
-    inert: true;
-    fetchpriority: true;
-    fetchPriority: true;
-    shadowRoot: true;
-    ariaHasPopup: true;
-    ariaLabel: true;
-    ariaLabelledBy: true;
-    about: true;
-    datatype: true;
-    inlist: true;
-    prefix: true;
-    property: true;
-    resource: true;
-    typeof: true;
-    vocab: true;
-    itemProp: true;
-    itemScope: true;
-    itemType: true;
-    itemID: true;
-    itemRef: true;
-    autoSave: true;
-    incremental: true;
-    results: true;
-    security: true;
-    unselectable: true;
-    on: true;
-    option: true;
-    fallback: true;
-};
-declare const VALID_DOM_TESTING_KEYS: string[];
-
 declare const HTML_TAGS: readonly ["div", "span", "a", "p", "ul", "li"];
-declare const SAFE_HTML_TAGS: readonly ["b", "i", "p", "ul", "li", "a", "span", "div", "br", "strong", "em", "u", "code", "pre", "blockquote"];
-declare const DEFAULT_KEYBOARD_CONFIG: Required<TKeyboardConfig>;
 
 declare const __brand: unique symbol;
 type Branded<T, B> = T & {
@@ -562,20 +115,7 @@ type TGetCallerLocationOptions = {
     /** Path prefix to strip from the returned line (default: process.cwd()) */
     stripPathPrefix?: string;
 };
-type TTableItem = {
-    key?: string;
-    start?: number;
-    end?: number;
-};
-type TProcessedTableItem = {
-    key: string | number;
-    duration: string;
-};
 
-type TPropMap = Record<string, boolean>;
-type TPropCategories = {
-    readonly [category: string]: TPropMap;
-};
 /**
  * A structural contract for any React component that might have
  * identification metadata.
@@ -1199,6 +739,58 @@ declare const isRecordOf: <V>(value: unknown, typeGuard: TTypeGuard<V>) => value
  * @returns A type guard function that returns `true` if all `requiredKeys` are found and defined.
  */
 declare const hasDefinedKeys: <T extends object>(requiredKeys: (keyof T)[]) => ((value: unknown) => value is T);
+/**
+ * ## 🧩 isShape — Recursive Structural Type Guard Factory
+ *
+ * Creates a **high-fidelity type guard** that validates whether an unknown object
+ * conforms to a specific structural "contract" defined by a schema of guards.
+ *
+ * ---
+ *
+ * ### ⚙️ Core Purpose
+ * - 🔹 **Eliminate `as` casting**: Moves from speculative assertions to deterministic verification.
+ * - 🔹 **Recursive Validation**: Safely audits nested object trees by composing guards.
+ * - 🔹 **Compile-Time Synchronization**: Using `[K in keyof T]` ensures the schema
+ *   stays in sync with the interface. If the interface changes, the guard will fail to compile.
+ *
+ * ---
+ *
+ * ### 📘 Example Usage
+ * ```ts
+ * interface UserProfile {
+ *   id: string;
+ *   settings: { theme: 'dark' | 'light' };
+ * }
+ *
+ * // Define the contract once
+ * const isUserProfile = isShape<UserProfile>({
+ *   id: isString,
+ *   settings: isShape({
+ *     theme: isInArray(['dark', 'light'] as const)
+ *   })
+ * });
+ *
+ * const rawData: unknown = await fetchApi();
+ *
+ * if (isUserProfile(rawData)) {
+ *   // ✅ rawData is now fully narrowed, including nested properties.
+ *   console.log(rawData.settings.theme);
+ * }
+ * ```
+ *
+ * ---
+ *
+ * ### 📌 Notes
+ * - **Exorcises Ghost Objects**: Unlike `{} as T`, this verifies every required key.
+ * - **Optional Support**: If a key is missing in the value but allowed in the schema,
+ *   the individual property guard must handle the `undefined` case.
+ * - **Zero Casts**: Internally leverages `isKeyInObject` for type-safe property discovery.
+ *
+ * @typeParam T - The target interface or object type to validate.
+ * @param schema - A mapping of keys from `T` to their corresponding `TTypeGuard`.
+ * @returns A type guard function that narrows `unknown` to `T`.
+ */
+declare const isShape: <T extends object>(schema: { [K in keyof T]: TTypeGuard<T[K]>; }) => TTypeGuard<T>;
 
 /**
  * Checks if a value is a **Buffer-like object**.
@@ -1516,6 +1108,7 @@ declare const CollectionTypeGuards: {
     readonly isKeyOfArray: <T extends readonly (string | number | symbol)[]>(keys: T) => TTypeGuard<T[number]>;
     readonly isInArray: <T>(target: readonly T[]) => TTypeGuard<T | undefined>;
     readonly hasKeys: <T extends object>(requiredKeys: (keyof T)[]) => ((value: unknown) => value is T);
+    readonly isShape: <T extends object>(schema: { [K in keyof T]: TTypeGuard<T[K]>; }) => TTypeGuard<T>;
 };
 
 /**
@@ -2543,4 +2136,246 @@ declare class LinkUtils {
     static readonly handleHashScroll: ({ event, href, behavior, block, }: THashScrollOptions) => boolean;
 }
 
-export { ANSI_COLOR_CODES, ArrayUtils, AssertionUtils, type Branded, CollectionTypeGuards, ColorUtils, ComputationUtils, CoreTypeGuards, DEFAULT_KEYBOARD_CONFIG, DebugUtils, DomUtils, FormatTypeGuards, HTML_TAGS, LOG_TYPES, LinkUtils, type ModifierKey, ObjectUtils, REGEX_CONSTANTS, ReactTypeGuards, RenamedArrayMethods, RenamedObjectMethods, SAFE_HTML_TAGS, type TAbsoluteURL, type TAnyFunction, type TArrayItems, type TArrayLengthMutationKeys, type TAssert, type TBaseImageObject, type TBufferLikeObject, type TCamelCase, type TCssRGB, type TElementLike, type TFixedLengthArray, type TGenericUrlObject, type TGetCallerLocationOptions, type THTMLTags, type THashScrollOptions, type THexByteString, type THighlighterMap, type TInternalUrl, type TJSONArrayString, type TJSONDataString, type TJSONObjectString, type TKebabCase, type TKeyboardActionResult, type TKeyboardConfig, type TLogOptions, type TLogType, type TNamedComponent, type TProcessedTableItem, type TPropCategories, type TPropMap, type TRGB, type TShortcutDefinition, type TSnakeCase, type TStaticMethods, type TTableItem, type TTypeGuard, TransformersUtils, VALID_DOM_PROPS, VALID_DOM_TESTING_KEYS, arrayFilter, arrayFilterNonNullable, arrayFlat, arrayFlatMap, arrayForEach, arrayIncludes, arrayMap, arrayReduce, assertIsAbsoluteUrl, assertIsArray, assertIsBigInt, assertIsBoolean, assertIsBufferLikeObject, assertIsCamelCase, assertIsDefined, assertIsFunction, assertIsInteger, assertIsInternalUrl, assertIsJSONArrayString, assertIsJSONObjectString, assertIsJsonString, assertIsMap, assertIsNil, assertIsNonEmptyString, assertIsNull, assertIsNumber, assertIsRGBTuple, assertIsSet, assertIsString, assertIsSymbol, assertIsUndefined, assertIsWeakMap, assertIsWeakSet, assertObject, capitalizeArray, capitalizeString, capitalizedKeys, contrastTextColor, extractRelativePath, generateKeyMap, getCallerLocation, getKeyboardAction, getLuminance, handleInternalHashScroll, hasChildren, hasDefinedKeys, hasNameMetadata, hasOnClick, hexToHSL, hexToNormalizedRGB, hexToRGB, hexToRGBShorthand, highlight, interpolateColor, isAbsoluteUrl, isArray, isArrayOf, isBigInt, isBoolean, isBufferLikeObject, isCamelCase, isComponentType, isDOMEntry, isDOMPropKey, isDarkColor, isDefined, isElementLike, isElementOfType, isEmail, isForwardRef, isFragment, isFunction, isHTMLString, isHexByteString, isInArray, isInstanceOf, isInteger, isInternalUrl, isJSONArrayString, isJSONObjectString, isJsonString, isKebabCase, isKeyInObject, isKeyOfArray, isKeyOfObject, isLumGreaterThan, isLumLessThan, isMap, isNil, isNonEmptyString, isNull, isNumber, isObject, isPhoneNumber, isPrimitive, isPromise, isPropValid, isRGBTuple, isReactElement, isReactPortal, isRecordOf, isRef, isRefObject, isSet, isSnakeCase, isString, isSymbol, isUndefined, isValidReactNode, isWeakMap, isWeakSet, logDev, normalizeImageSrc, normalizeUrl, objectEntries, objectFromEntries, objectGet, objectHas, objectKeys, objectSet, objectValues, preloadImages, serialize, stripHash, toCamelCase, toKebabCase, toKeyByField, toSnakeCase, validateRGB };
+/**
+ * ## 🌐 fetchJson — Fetch and Parse JSON from a URL
+ *
+ * Performs a `fetch` request and attempts to parse the response as JSON.
+ * Throws a detailed error if the request fails or the response is not valid JSON.
+ *
+ * ---
+ *
+ * ### Example
+ *
+ * ```ts
+ * const data = await fetchJson<{ id: number; name: string }>(
+ *   'https://api.example.com/users/1'
+ * );
+ * console.log(data.id, data.name);
+ * ```
+ *
+ * @template T - Expected type of the JSON response
+ * @param url - URL to fetch JSON from
+ * @returns Parsed JSON data of type `T`
+ * @throws Error if fetch fails or response is invalid JSON
+ */
+declare function fetchJson<T = unknown>(url: string): Promise<T>;
+/**
+ * ## ⏱ delay — Pause Execution for a Duration
+ *
+ * Returns a Promise that resolves after a specified number of milliseconds.
+ * Useful for throttling, rate-limiting, or waiting between async operations.
+ *
+ * ---
+ *
+ * ### Example
+ *
+ * ```ts
+ * await delay(1000); // Pause for 1 second
+ * console.log('Done waiting!');
+ * ```
+ *
+ * @param ms - Number of milliseconds to wait
+ * @returns Promise that resolves after `ms` milliseconds
+ */
+declare const delay: (ms: number) => Promise<void>;
+/**
+ * ## 🔁 retry — Retry an Async Function with Exponential Backoff
+ *
+ * Executes an async function multiple times if it fails, with an **exponential backoff** strategy.
+ * Automatically handles transient failures or rate-limiting errors.
+ *
+ * ---
+ *
+ * ### Example
+ *
+ * ```ts
+ * const result = await retry(() => fetchJson('/api/data'), 3, 500);
+ * console.log(result);
+ * ```
+ *
+ * @template T - Return type of the async function
+ * @param fn - Async function to retry
+ * @param retries - Maximum number of retry attempts (default: 5)
+ * @param delayMs - Base delay in milliseconds for exponential backoff (default: 500)
+ * @returns Result of the async function if successful
+ * @throws Last encountered error if all retries fail
+ */
+declare function retry<T>(fn: () => Promise<T>, retries?: number, delayMs?: number): Promise<T>;
+
+/**
+ * Combines multiple React refs (callback refs or object refs) into a single ref callback.
+ *
+ * This is especially useful when a component needs to:
+ * 1. Forward a ref to its parent via `forwardRef`
+ * 2. Maintain its own internal ref for hooks like `useInView`, animations, or measurements
+ *
+ * The returned callback handles both:
+ * - Function refs (calls the function with the new value)
+ * - Object refs (assigns the `current` property)
+ * - Properly supports `null` for unmounting
+ *
+ * @example
+ * ```ts
+ * const combinedRef = mergeRefs(forwardedRef, internalRef);
+ * <div ref={combinedRef} />
+ * ```
+ *
+ * @param refs - One or more React refs (callback or object refs)
+ * @returns A single callback that updates all provided refs with the same value
+ */
+declare const mergeRefs: <T>(...refs: (Ref<T> | undefined)[]) => RefCallback<T>;
+/**
+ * Lazily evaluates the properties of an object that are functions and caches the results.
+ *
+ * This utility is useful when you have an object with expensive-to-compute properties
+ * (functions) that you don’t want to execute until they are actually accessed. It also
+ * ensures that each property is only computed **once**, even if accessed multiple times.
+ *
+ * The original object is **not mutated**; all computed results are stored in an internal cache.
+ *
+ * ### Features
+ * - Lazy evaluation of function properties.
+ * - Caches results for repeated access.
+ * - Safe for shared or frozen objects.
+ * - Works only on original string keys of the object.
+ *
+ * ### Example
+ * ```ts
+ * const config = {
+ *   a: 10,
+ *   b: () => Math.random() * 100,
+ *   c: () => 'computed',
+ * };
+ *
+ * const lazyConfig = lazyProxy(config);
+ *
+ * console.log(lazyConfig.a); // 10
+ * console.log(lazyConfig.b); // e.g., 42.3 (evaluated only once)
+ * console.log(lazyConfig.b); // same value as above (cached)
+ * console.log(lazyConfig.c); // 'computed'
+ * ```
+ *
+ * ### Use Cases
+ * - Configuration objects with expensive default values.
+ * - Large objects where some properties are rarely used.
+ * - Avoiding repeated computation in utility objects or library settings.
+ * - Safe lazy initialization in complex apps without mutating original objects.
+ *
+ * @param obj - The object whose function properties should be lazily evaluated.
+ * @returns A proxied version of the object where function properties are evaluated lazily and cached.
+ */
+declare function lazyProxy<T extends Record<string, unknown>>(obj: T): T;
+/**
+ * Merges CSS variables with an optional style object.
+ *
+ * @param vars - An object where keys are CSS variable names (like '--my-var') and values are strings
+ * @param style - Optional existing style object to merge
+ * @returns A CSSProperties object ready to pass to a React component
+ */
+declare function mergeCssVars<T extends Record<string, string | number | undefined>>(vars: T, style?: CSSProperties): CSSProperties;
+/**
+ * Merges a user-provided event handler with an internal component handler.
+ *
+ * The `internalHandler` will only execute if the `userHandler` does not call
+ * `event.preventDefault()`. This allows users of your component to opt-out
+ * of default behaviors.
+ *
+ * @template E - The type of the SyntheticEvent (e.g., React.MouseEvent)
+ * @param userHandler - The external handler passed via props
+ * @param internalHandler - The library/internal logic that should run by default
+ * @returns A single function that orchestrates both calls
+ *
+ * @example
+ * ```tsx
+ * const handleClick = mergeEventHandlerClicks<React.MouseEvent>(
+ *   props.onClick,
+ *   (e) => console.log("Internal logic ran!")
+ * );
+ *
+ * // In the component:
+ * <button onClick={handleClick}>Click Me</button>
+ * ```
+ */
+declare function mergeEventHandlerClicks<E extends SyntheticEvent>(userHandler?: (event: E) => void, internalHandler?: (event: E) => void): (event: E) => void;
+/**
+ * Automatically extracts valid DOM props from a combined props object.
+ *
+ * This utility prevents React warnings like: "React does not recognize the `prop` on a DOM element."
+ * It works by filtering the object against a whitelist of valid HTML attributes at runtime,
+ * while maintaining strict TypeScript narrowing so the return type matches the target element.
+ *
+ * ### Features
+ * - **Auto-Filtering**: No need to manually maintain an array of keys to delete.
+ * - **Type Safe**: Automatically narrows the return type to `ComponentPropsWithoutRef<T>`.
+ * - **Standard Compliant**: Supports all standard HTML attributes, `data-*`, and `aria-*` props.
+ *
+ * ### Example
+ * ```tsx
+ * interface MyButtonProps extends ComponentPropsWithoutRef<'button'> {
+ *   mainCircleSize: number; // Custom prop: will be stripped
+ *   variant: 'primary';    // Custom prop: will be stripped
+ * }
+ *
+ * const MyButton = (props: MyButtonProps) => {
+ *   // domProps is automatically inferred as ComponentPropsWithoutRef<'button'>
+ *   // 'mainCircleSize' and 'variant' are removed automatically.
+ *   const domProps = extractDOMProps<'button', MyButtonProps>(props);
+ *
+ *   return <button {...domProps}>Click Me</button>;
+ * };
+ * ```
+ *
+ * @template TElement - The HTML element type (e.g., 'div', 'button', 'span')
+ * @template TFullProps - The combined custom and DOM props interface
+ *
+ * @param props - The full props object containing both custom and DOM-valid keys.
+ * @returns A cleaned object containing only valid DOM properties for the specified element.
+ */
+declare function extractDOMProps<TElement extends ElementType, TFullProps extends ComponentPropsWithoutRef<TElement>>(props: TFullProps): ComponentPropsWithoutRef<TElement>;
+/**
+ * Filters React children by a specific component display name.
+ *
+ * This utility iterates over a ReactNode tree and returns only the children
+ * that are valid React elements with a `displayName` matching the provided string.
+ * It is especially useful for composite components like steppers or tabs,
+ * where you want to operate only on specific subcomponents while ignoring others.
+ *
+ * The original `children` array is **not mutated**; a new filtered array is returned.
+ *
+ * ### Features
+ * - Type-safe filtering of React elements.
+ * - Skips non-React elements automatically.
+ * - Returns a typed array of `ReactElement` for further processing.
+ *
+ * ### Example
+ * ```tsx
+ * const steps = filterChildrenByDisplayName(children, 'StepperStep');
+ * steps.forEach(step => console.log(step.props));
+ * ```
+ *
+ * ### Use Cases
+ * - Stepper components: only extract `StepperStep` children for layout/logic.
+ * - Tab components: only process `TabPanel` children.
+ * - Any composite React component requiring selective child processing.
+ *
+ * @param children - The ReactNode children to filter.
+ * @param displayName - The displayName of the component type to include.
+ * @returns An array of ReactElement matching the given displayName.
+ */
+declare function filterChildrenByDisplayName<T extends ReactNode>(children: T, displayName: string): ReactElement[];
+
+declare const ProcessorUtils: {
+    readonly fetchJson: typeof fetchJson;
+    readonly delay: (ms: number) => Promise<void>;
+    readonly retry: typeof retry;
+};
+declare const ReactProcessorUtils: {
+    readonly mergeRefs: <T>(...refs: (react.Ref<T> | undefined)[]) => react.RefCallback<T>;
+    readonly lazyProxy: typeof lazyProxy;
+    readonly mergeCssVars: typeof mergeCssVars;
+    readonly mergeEventHandlerClicks: typeof mergeEventHandlerClicks;
+    readonly extractDOMProps: typeof extractDOMProps;
+    readonly filterChildrenByDisplayName: typeof filterChildrenByDisplayName;
+};
+
+export { ArrayUtils, AssertionUtils, CollectionTypeGuards, ColorUtils, ComputationUtils, CoreTypeGuards, DebugUtils, DomUtils, FormatTypeGuards, LinkUtils, ObjectUtils, ProcessorUtils, ReactProcessorUtils, ReactTypeGuards, RenamedArrayMethods, RenamedObjectMethods, TransformersUtils, arrayFilter, arrayFilterNonNullable, arrayFlat, arrayFlatMap, arrayForEach, arrayIncludes, arrayMap, arrayReduce, assertIsAbsoluteUrl, assertIsArray, assertIsBigInt, assertIsBoolean, assertIsBufferLikeObject, assertIsCamelCase, assertIsDefined, assertIsFunction, assertIsInteger, assertIsInternalUrl, assertIsJSONArrayString, assertIsJSONObjectString, assertIsJsonString, assertIsMap, assertIsNil, assertIsNonEmptyString, assertIsNull, assertIsNumber, assertIsRGBTuple, assertIsSet, assertIsString, assertIsSymbol, assertIsUndefined, assertIsWeakMap, assertIsWeakSet, assertObject, capitalizeArray, capitalizeString, capitalizedKeys, contrastTextColor, delay, extractDOMProps, extractRelativePath, fetchJson, filterChildrenByDisplayName, generateKeyMap, getCallerLocation, getKeyboardAction, getLuminance, handleInternalHashScroll, hasChildren, hasDefinedKeys, hasNameMetadata, hasOnClick, hexToHSL, hexToNormalizedRGB, hexToRGB, hexToRGBShorthand, highlight, interpolateColor, isAbsoluteUrl, isArray, isArrayOf, isBigInt, isBoolean, isBufferLikeObject, isCamelCase, isComponentType, isDOMEntry, isDOMPropKey, isDarkColor, isDefined, isElementLike, isElementOfType, isEmail, isForwardRef, isFragment, isFunction, isHTMLString, isHexByteString, isInArray, isInstanceOf, isInteger, isInternalUrl, isJSONArrayString, isJSONObjectString, isJsonString, isKebabCase, isKeyInObject, isKeyOfArray, isKeyOfObject, isLumGreaterThan, isLumLessThan, isMap, isNil, isNonEmptyString, isNull, isNumber, isObject, isPhoneNumber, isPrimitive, isPromise, isPropValid, isRGBTuple, isReactElement, isReactPortal, isRecordOf, isRef, isRefObject, isSet, isShape, isSnakeCase, isString, isSymbol, isUndefined, isValidReactNode, isWeakMap, isWeakSet, lazyProxy, logDev, mergeCssVars, mergeEventHandlerClicks, mergeRefs, normalizeImageSrc, normalizeUrl, objectEntries, objectFromEntries, objectGet, objectHas, objectKeys, objectSet, objectValues, preloadImages, retry, serialize, stripHash, toCamelCase, toKebabCase, toKeyByField, toSnakeCase, validateRGB };