@sohanemon/utils 6.4.7 → 7.0.0

package/dist/index-CG2oc6F7.d.ts

@@ -1,970 +0,0 @@
-import { ClassValue } from "clsx";
-import * as React from "react";
-
-//#region src/functions/cookie.d.ts
-
-/**
- * Sets a client-side cookie with optional expiration and path.
- *
- * @param name - The name of the cookie
- * @param value - The value to store in the cookie
- * @param days - Optional number of days until the cookie expires
- * @param path - Optional path for the cookie (defaults to '/')
- *
- * @example
- * // Set a cookie that expires in 7 days
- * setClientSideCookie('userId', '12345', 7);
- *
- * @example
- * // Set a session cookie (no expiration)
- * setClientSideCookie('sessionId', 'abc123');
- */
-declare const setClientSideCookie: (name: string, value: string, days?: number, path?: string) => void;
-/**
- * Deletes a client-side cookie by setting its expiration to a past date.
- *
- * @param name - The name of the cookie to delete
- * @param path - Optional path for the cookie (defaults to '/')
- *
- * @example
- * // Delete a cookie
- * deleteClientSideCookie('userId');
- */
-declare const deleteClientSideCookie: (name: string, path?: string) => void;
-/**
- * Checks if a client-side cookie exists.
- *
- * @param name - The name of the cookie to check
- * @returns True if the cookie exists, false otherwise
- *
- * @example
- * // Check if a cookie exists
- * if (hasClientSideCookie('userId')) {
- *   console.log('User is logged in');
- * }
- */
-declare const hasClientSideCookie: (name: string) => boolean;
-/**
- * Retrieves the value of a client-side cookie.
- *
- * @param name - The name of the cookie to retrieve
- * @returns An object containing the cookie value, or undefined if not found
- *
- * @example
- * // Get a cookie value
- * const { value } = getClientSideCookie('userId');
- * if (value) {
- *   console.log('User ID:', value);
- * }
- */
-declare const getClientSideCookie: (name: string) => {
-  value: string | undefined;
-};
-//#endregion
-//#region src/functions/deepmerge.d.ts
-type TAllKeys<T> = T extends any ? keyof T : never;
-type TIndexValue<T, K$1 extends PropertyKey, D = never> = T extends any ? K$1 extends keyof T ? T[K$1] : D : never;
-type TPartialKeys<T, K$1 extends keyof T> = Omit<T, K$1> & Partial<Pick<T, K$1>> extends infer O ? { [P in keyof O]: O[P] } : never;
-type TFunction = (...a: any[]) => any;
-type TPrimitives = string | number | boolean | bigint | symbol | Date | TFunction;
-type DeepMergeOptions = {
-  arrayMerge?: 'replace' | 'concat' | 'merge' | ((target: any[], source: any[]) => any[]);
-  clone?: boolean;
-  customMerge?: (key: string | symbol, targetValue: any, sourceValue: any) => any;
-  functionMerge?: 'replace' | 'compose';
-  maxDepth?: number;
-};
-type TMerged<T> = [T] extends [Array<any>] ? { [K in keyof T]: TMerged<T[K]> } : [T] extends [TPrimitives] ? T : [T] extends [object] ? TPartialKeys<{ [K in TAllKeys<T>]: TMerged<TIndexValue<T, K>> }, never> : T;
-/**
- * Deeply merges multiple objects, with later sources taking precedence.
- * Handles nested objects, arrays, and special object types with circular reference detection.
- *
- * Features:
- * - Deep merging of nested objects
- * - Configurable array merging strategies
- * - Circular reference detection and handling
- * - Support for symbols and special objects (Date, RegExp, etc.)
- * - Type-safe with improved generics
- * - Optional cloning to avoid mutation
- * - Custom merge functions for specific keys
- *
- * @template T - The target object type
- * @param target - The target object to merge into
- * @param sources - Source objects to merge from (can have additional properties)
- * @param options - Configuration options
- * @param options.clone - Whether to clone the target (default: true)
- * @param options.customMerge - Custom merge function for specific keys
- * @param options.arrayMerge - How to merge arrays: 'replace' (default), 'concat', or 'merge'
- * @param options.functionMerge - How to merge functions: 'replace' (default) or 'compose'
- * @param options.maxDepth - Maximum recursion depth (default: 100)
- * @returns The merged object with proper typing
- *
- * @example
- * // Basic shallow merge
- * deepmerge({ a: 1 }, { b: 2 }) // { a: 1, b: 2 }
- *
- * @example
- * // Deep merge of nested objects
- * deepmerge({ user: { name: 'John' } }, { user: { age: 30 } })
- * // { user: { name: 'John', age: 30 } }
- *
- * @example
- * // Array concatenation
- * deepmerge({ tags: ['react'] }, { tags: ['typescript'] }, { arrayMerge: 'concat' })
- * // { tags: ['react', 'typescript'] }
- *
- * @example
- * // Array replacement (default)
- * deepmerge({ items: [1, 2] }, { items: [3, 4] })
- * // { items: [3, 4] }
- *
- * @example
- * // Custom array merging
- * deepmerge(
- *   { scores: [85, 90] },
- *   { scores: [95] },
- *   { arrayMerge: (target, source) => [...target, ...source] }
- * )
- * // { scores: [85, 90, 95] }
- *
- * @example
- * // Configuration merging
- * const defaultConfig = { theme: 'light', features: { darkMode: false } };
- * const userConfig = { theme: 'dark', features: { darkMode: true, animations: true } };
- * deepmerge(defaultConfig, userConfig);
- * // { theme: 'dark', features: { darkMode: true, animations: true } }
- *
- * @example
- * // State updates in reducers
- * const initialState = { user: { profile: { name: '' } }, settings: {} };
- * const action = { user: { profile: { name: 'Alice' } }, settings: { theme: 'dark' } };
- * const newState = deepmerge(initialState, action);
- *
- * @example
- * // Merging API responses
- * const cachedData = { posts: [{ id: 1, title: 'Old' }] };
- * const freshData = { posts: [{ id: 1, title: 'Updated', author: 'Bob' }] };
- * deepmerge(cachedData, freshData);
- * // { posts: [{ id: 1, title: 'Updated', author: 'Bob' }] }
- *
- * @example
- * // Function composition
- * const log1 = () => console.log('first');
- * const log2 = () => console.log('second');
- * const composed = deepmerge(log1, log2, { functionMerge: 'compose' });
- * composed(); // logs 'first' then 'second'
- */
-declare function deepmerge<T extends Record<string, any>, S extends Record<string, any>[]>(target: T, ...sources: S): TMerged<T | S[number]>;
-declare function deepmerge<T extends Record<string, any>, S extends Record<string, any>[]>(target: T, sources: S, options?: DeepMergeOptions): TMerged<T | S[number]>;
-//#endregion
-//#region src/functions/hydrate.d.ts
-type Hydrate<T> = T extends null ? undefined : T extends (infer U)[] ? Hydrate<U>[] : T extends object ? { [K in keyof T]: Hydrate<T[K]> } : T;
-/**
- * Converts all `null` values to `undefined` in the data structure recursively.
- *
- * @param data - Any input data (object, array, primitive)
- * @returns Same type as input, but with all nulls replaced by undefined
- *
- * @example
- * ```ts
- * // Basic object hydration
- * hydrate({ name: null, age: 25 }) // { name: undefined, age: 25 }
- *
- * // Nested object hydration
- * hydrate({
- *   user: { email: null, profile: { avatar: null } },
- *   settings: { theme: 'dark' }
- * })
- * // { user: { email: undefined, profile: { avatar: undefined } }, settings: { theme: 'dark' } }
- *
- * // Array hydration
- * hydrate([null, 'hello', null, 42]) // [undefined, 'hello', undefined, 42]
- *
- * // Mixed data structures
- * hydrate({
- *   posts: [null, { title: 'Hello', content: null }],
- *   metadata: { published: null, tags: ['react', null] }
- * })
- * ```
- *
- * @example
- * ```ts
- * // API response normalization
- * const apiResponse = await fetch('/api/user');
- * const rawData = await apiResponse.json(); // May contain null values
- * const normalizedData = hydrate(rawData); // Convert nulls to undefined
- *
- * // Database result processing
- * const dbResult = query('SELECT * FROM users'); // Some fields may be NULL
- * const cleanData = hydrate(dbResult); // Normalize for consistent handling
- *
- * // Form data sanitization
- * const formData = getFormValues(); // May have null values from empty fields
- * const sanitizedData = hydrate(formData); // Prepare for validation/state
- * ```
- */
-declare function hydrate<T>(data: T): Hydrate<T>;
-//#endregion
-//#region src/functions/object.d.ts
-/**
- * Type representing a path split into segments
- * @template S - The original path string type
- */
-type SplitPath<S extends string> = S extends `${infer First}.${infer Rest}` ? [First, ...SplitPath<Rest>] : [S];
-/**
- * Recursive type to resolve nested object types based on path
- * @template T - Current object type
- * @template K - Array of path segments
- */
-type GetValue<T, K$1 extends Array<string | number>> = K$1 extends [infer First, ...infer Rest] ? First extends keyof T ? GetValue<T[First], Rest extends Array<string | number> ? Rest : []> : First extends `${number}` ? T extends any[] ? GetValue<T[number], Rest extends Array<string | number> ? Rest : []> : undefined : undefined : T;
-/**
- * Get a nested value from an object using array path segments
- * @template T - Object type
- * @template K - Path segments array type
- * @template D - Default value type
- * @param obj - Source object
- * @param path - Array of path segments
- * @param defaultValue - Fallback value if path not found
- * @returns Value at path or default value
- *
- * @example
- * getObjectValue({a: [{b: 1}]}, ['a', 0, 'b']) // 1
- */
-declare function getObjectValue<T, K$1 extends Array<string | number>, D>(obj: T, path: K$1, defaultValue: D): Exclude<GetValue<T, K$1>, undefined> | D;
-/**
- * Get a nested value from an object using array path segments
- * @template T - Object type
- * @template K - Path segments array type
- * @param obj - Source object
- * @param path - Array of path segments
- * @returns Value at path or undefined
- *
- * @example
- * getObjectValue({a: [{b: 1}]}, ['a', 0, 'b']) // 1
- */
-declare function getObjectValue<T, K$1 extends Array<string | number>>(obj: T, path: K$1): GetValue<T, K$1> | undefined;
-/**
- * Get a nested value from an object using dot notation path
- * @template T - Object type
- * @template S - Path string literal type
- * @template D - Default value type
- * @param obj - Source object
- * @param path - Dot-separated path string
- * @param defaultValue - Fallback value if path not found
- * @returns Value at path or default value
- *
- * @example
- * getObjectValue({a: [{b: 1}]}, 'a.0.b', 2) // 1
- */
-declare function getObjectValue<T, S extends string, D>(obj: T, path: S, defaultValue: D): Exclude<GetValue<T, SplitPath<S>>, undefined> | D;
-/**
- * Get a nested value from an object using dot notation path
- * @template T - Object type
- * @template S - Path string literal type
- * @param obj - Source object
- * @param path - Dot-separated path string
- * @returns Value at path or undefined
- *
- * @example
- * getObjectValue({a: [{b: 1}]}, 'a.0.b') // 1
- */
-declare function getObjectValue<T, S extends string>(obj: T, path: S): GetValue<T, SplitPath<S>> | undefined;
-/**
- * Extend an object or function with additional properties while
- * preserving the original type information.
- *
- * Works with both plain objects and callable functions since
- * functions in JavaScript are objects too. Also handles nullable types.
- *
- * @template T The base object or function type (can be null/undefined)
- * @template P The additional properties type
- *
- * @param base - The object or function to extend (can be null/undefined)
- * @param props - An object containing properties to attach
- *
- * @returns The same object/function, augmented with the given properties, or the original value if null/undefined
- *
- * @example
- * ```ts
- * // Extend a plain object
- * const config = extendProps({ apiUrl: '/api' }, { timeout: 5000 });
- * // config has both apiUrl and timeout properties
- *
- * // Extend a function with metadata
- * const fetchData = (url: string) => fetch(url).then(r => r.json());
- * const enhancedFetch = extendProps(fetchData, {
- *   description: 'Data fetching utility',
- *   version: '1.0'
- * });
- * // enhancedFetch is callable and has description/version properties
- *
- * // Create plugin system
- * const basePlugin = { name: 'base', enabled: true };
- * const authPlugin = extendProps(basePlugin, {
- *   authenticate: (token: string) => validateToken(token)
- * });
- *
- * // Build configuration objects
- * const defaultSettings = { theme: 'light', lang: 'en' };
- * const userSettings = extendProps(defaultSettings, {
- *   theme: 'dark',
- *   notifications: true
- * });
- *
- * // Handle nullable types (e.g., Supabase Session | null)
- * const session: Session | null = getSession();
- * const extendedSession = extendProps(session, { customProp: 'value' });
- * // extendedSession is (Session & { customProp: string }) | null
- * ```
- */
-declare function extendProps<T, P$1 extends object>(base: T, props: P$1): T extends null | undefined ? T : T & P$1;
-//#endregion
-//#region src/functions/poll.d.ts
-/**
- * Repeatedly polls an async `cond` function UNTIL it returns a TRUTHY value,
- * or until the operation times out or is aborted.
- *
- * Designed for waiting on async jobs, external state, or delayed availability.
- *
- * @template T The type of the successful result.
- *
- * @param cond
- * A function returning a Promise that resolves to:
- *   - a truthy value `T` → stop polling and return it
- *   - falsy/null/undefined → continue polling
- *
- * @param options
- * Configuration options:
- * - `interval` (number) — Time between polls in ms (default: 5000 ms)
- * - `timeout` (number) — Max total duration before failing (default: 5 min)
- * - `jitter` (boolean) — Add small random offset (±10%) to intervals to avoid sync bursts (default: true)
- * - `signal` (AbortSignal) — Optional abort signal to cancel polling
- *
- * @returns
- * Resolves with the truthy value `T` when successful.
- * Throws `AbortError` if aborted
- *
- * @example
- * ```ts
- * // Poll for job completion
- * const job = await poll(async () => {
- *   const status = await getJobStatus();
- *   return status === 'done' ? status : null;
- * }, { interval: 3000, timeout: 60000 });
- * ```
- *
- * @example
- * ```ts
- * // Wait for API endpoint to be ready
- * const apiReady = await poll(async () => {
- *   try {
- *     await fetch('/api/health');
- *     return true;
- *   } catch {
- *     return null;
- *   }
- * }, { interval: 1000, timeout: 30000 });
- * ```
- *
- * @example
- * ```ts
- * // Poll with abort signal for cancellation
- * const controller = new AbortController();
- * setTimeout(() => controller.abort(), 10000); // Cancel after 10s
- *
- * try {
- *   const result = await poll(
- *     () => checkExternalService(),
- *     { interval: 2000, signal: controller.signal }
- *   );
- * } catch (err) {
- *   if (err.name === 'AbortError') {
- *     console.log('Polling was cancelled');
- *   }
- * }
- * ```
- *
- * @example
- * ```ts
- * // Poll for user action completion
- * const userConfirmed = await poll(async () => {
- *   const confirmations = await getPendingConfirmations();
- *   return confirmations.length > 0 ? confirmations[0] : null;
- * }, { interval: 5000, timeout: 300000 }); // 5 min timeout
- * ```
- */
-declare function poll<T>(cond: () => Promise<T | null | false | undefined>, {
-  interval,
-  timeout,
-  jitter,
-  signal
-}?: Partial<{
-  interval: number;
-  timeout: number;
-  signal: AbortSignal;
-  jitter: boolean;
-}>): Promise<T>;
-//#endregion
-//#region src/functions/schedule.d.ts
-/**
- * A task function that can be synchronous or asynchronous.
- */
-type Task = () => Promise<void> | void;
-/**
- * Options for configuring the schedule function.
- */
-interface ScheduleOpts {
-  /** Number of retry attempts on failure. Defaults to 0. */
-  retry?: number;
-  /** Delay in milliseconds between retries. Defaults to 0. */
-  delay?: number;
-  /** Maximum time in milliseconds to wait for the task to complete. */
-  timeout?: number;
-}
-/**
- * Runs a function asynchronously in the background without blocking the main thread.
- *
- * Executes the task immediately using setTimeout, with optional retry logic on failure.
- * Useful for non-critical operations like analytics, logging, or background processing.
- * Logs execution time and retry attempts to the console.
- *
- * @param task - The function to execute asynchronously
- * @param options - Configuration options for retries and timing
- *
- * @example
- * ```ts
- * // Simple background task
- * schedule(() => {
- *   console.log('Background work done');
- * });
- *
- * // Task with retry on failure
- * schedule(
- *   () => sendAnalytics(),
- *   { retry: 3, delay: 1000 }
- * );
- * ```
- */
-declare function schedule(task: Task, options?: ScheduleOpts): void;
-//#endregion
-//#region src/functions/shield.d.ts
-/**
- * A helper to run sync or async operations safely without try/catch.
- *
- * Returns a tuple `[error, data]`:
- * - `error`: the thrown error (if any), otherwise `null`
- * - `data`: the resolved value (if successful), otherwise `null`
- *
- * @example
- * ```ts
- * // Synchronous error handling
- * const [err, value] = shield(() => {
- *   if (Math.random() > 0.5) throw new Error('Random failure');
- *   return 'success';
- * });
- * if (err) {
- *   console.error('Operation failed:', err);
- * } else {
- *   console.log('Result:', value);
- * }
- *
- * // Asynchronous error handling
- * const [asyncErr, result] = await shield(async () => {
- *   const response = await fetch('/api/data');
- *   if (!response.ok) throw new Error('API error');
- *   return response.json();
- * });
- * if (asyncErr) {
- *   console.error('API call failed:', asyncErr);
- * } else {
- *   processData(result);
- * }
- *
- * // API calls with fallbacks
- * const [fetchErr, data] = await shield(fetchUserData(userId));
- * const userData = fetchErr ? getCachedUserData(userId) : data;
- *
- * // File operations
- * const [fileErr, content] = shield(() => readFileSync('config.json'));
- * if (fileErr) {
- *   console.warn('Could not read config, using defaults');
- *   return defaultConfig;
- * }
- * ```
- *
- * @example
- * ```ts
- * // In async functions
- * async function safeApiCall() {
- *   const [err, result] = await shield(callExternalAPI());
- *   if (err) {
- *     await logError(err);
- *     return null;
- *   }
- *   return result;
- * }
- *
- * // In event handlers
- * function handleSubmit(formData) {
- *   const [validationErr, validatedData] = shield(() => validateForm(formData));
- *   if (validationErr) {
- *     showValidationError(validationErr);
- *     return;
- *   }
- *   submitData(validatedData);
- * }
- * ```
- */
-declare function shield<T, E = Error>(operation: Promise<T>): Promise<[E | null, T | null]>;
-declare function shield<T, E = Error>(operation: () => T): [E | null, T | null];
-//#endregion
-//#region src/functions/utils.d.ts
-/**
- * Utility to merge class names with Tailwind CSS and additional custom merging logic.
- *
- * @param {...ClassValue[]} inputs - Class names to merge.
- * @returns {string} - A string of merged class names.
- *
- * @example
- * ```ts
- * cn('px-2 py-1', 'bg-red-500') // 'px-2 py-1 bg-red-500'
- * cn('px-2', 'px-4') // 'px-4' (Tailwind resolves conflicts)
- * ```
- */
-declare function cn(...inputs: ClassValue[]): string;
-/**
- * @deprecated Use isLinkActive instead.
- *
- * Determines if a navigation link is active based on the current path.
- *
- * @param  href - The target URL.
- * @param  path - The current browser path.
- * @returns - True if the navigation is active, false otherwise.
- *
- * @example
- * ```ts
- * isNavActive('/about', '/about/team') // true
- * isNavActive('/contact', '/about') // false
- * ```
- */
-declare function isNavActive(href: string, path: string): boolean;
-/**
- * Checks if a link is active, considering optional localization prefixes.
- *
- * Compares paths while ignoring locale prefixes (e.g., /en/, /fr/) for consistent
- * navigation highlighting across different language versions of the same page.
- *
- * @param params - Parameters object.
- * @param params.path - The target path of the link.
- * @param params.currentPath - The current browser path.
- * @param params.locales - Supported locale prefixes to ignore during comparison.
- * @param params.exact - Whether to require exact path match (default: true). If false, checks if current path starts with target path.
- * @returns True if the link is active, false otherwise.
- *
- * @example
- * ```ts
- * // Exact match
- * isLinkActive({ path: '/about', currentPath: '/about' }) // true
- * isLinkActive({ path: '/about', currentPath: '/about/team' }) // false
- *
- * // With locales
- * isLinkActive({ path: '/about', currentPath: '/en/about' }) // true
- * isLinkActive({ path: '/about', currentPath: '/fr/about' }) // true
- *
- * // Partial match
- * isLinkActive({ path: '/blog', currentPath: '/blog/post-1', exact: false }) // true
- * ```
- */
-declare function isLinkActive({
-  path,
-  currentPath,
-  locales,
-  exact
-}: {
-  path: string;
-  currentPath: string;
-  locales?: string[];
-  exact?: boolean;
-}): boolean;
-/**
- * Cleans a file path by removing the `/public/` prefix if present.
- *
- * Useful when working with static assets that may have been processed
- * or when normalizing paths between development and production environments.
- *
- * @param src - The source path to clean.
- * @returns The cleaned path with `/public/` prefix removed and whitespace trimmed.
- *
- * @example
- * ```ts
- * cleanSrc('/public/images/logo.png') // '/images/logo.png'
- * cleanSrc('images/logo.png') // 'images/logo.png'
- * cleanSrc('  /public/docs/readme.md  ') // '/docs/readme.md'
- * ```
- */
-declare function cleanSrc(src: string): string;
-/**
- * Smoothly scrolls to the top or bottom of a specified container.
- *
- * Provides smooth scrolling animation to either end of a scrollable element.
- * Accepts either a CSS selector string or a React ref to the container element.
- *
- * @param containerSelector - The CSS selector string or React ref for the scrollable container.
- * @param to - Direction to scroll: 'top' for top of container, 'bottom' for bottom.
- *
- * @example
- * ```ts
- * // Scroll to top using selector
- * scrollTo('.main-content', 'top');
- *
- * // Scroll to bottom using ref
- * scrollTo(containerRef, 'bottom');
- * ```
- */
-declare const scrollTo: (containerSelector: string | React.RefObject<HTMLDivElement>, to: "top" | "bottom") => void;
-/**
- * Copies a given string to the clipboard using the modern Clipboard API.
- *
- * Safely attempts to copy text to the user's clipboard. Falls back gracefully
- * if the Clipboard API is not available or if the operation fails.
- *
- * @param value - The text value to copy to the clipboard.
- * @param onSuccess - Optional callback executed after successful copy operation.
- *
- * @example
- * ```ts
- * copyToClipboard('Hello World!', () => {
- *   console.log('Text copied successfully');
- * });
- * ```
- */
-declare const copyToClipboard: (value: string, onSuccess?: () => void) => void;
-/**
- * Converts various case styles (camelCase, PascalCase, kebab-case, snake_case) into readable normal case.
- *
- * Transforms technical naming conventions into human-readable titles by:
- * - Adding spaces between words
- * - Capitalizing the first letter of each word
- * - Handling common separators (-, _, camelCase boundaries)
- *
- * @param inputString - The string to convert (supports camelCase, PascalCase, kebab-case, snake_case).
- * @returns The converted string in normal case (title case).
- *
- * @example
- * ```ts
- * convertToNormalCase('camelCase') // 'Camel Case'
- * convertToNormalCase('kebab-case') // 'Kebab Case'
- * convertToNormalCase('snake_case') // 'Snake Case'
- * convertToNormalCase('PascalCase') // 'Pascal Case'
- * ```
- */
-declare function convertToNormalCase(inputString: string): string;
-/**
- * Converts a string to a URL-friendly slug by trimming, converting to lowercase,
- * replacing diacritics, removing invalid characters, and replacing spaces with hyphens.
- * @param {string} [str] - The input string to convert.
- * @returns {string} The generated slug.
- * @example
- * convertToSlug("Hello World!"); // "hello-world"
- * convertToSlug("Déjà Vu"); // "deja-vu"
- */
-declare const convertToSlug: (str: string) => string;
-/**
- * Checks if the code is running in a server-side environment.
- *
- * @returns - True if the code is executed in SSR (Server-Side Rendering) context, false otherwise
- *
- * @example
- * ```ts
- * if (isSSR) {
- *   // Server-side only code
- *   console.log('Running on server');
- * } else {
- *   // Client-side only code
- *   window.addEventListener('load', () => {});
- * }
- * ```
- */
-declare const isSSR: boolean;
-/**
- * Converts an SVG string to a Base64-encoded string.
- *
- * @param str - The SVG string to encode
- * @returns - Base64-encoded string representation of the SVG
- *
- * @example
- * ```ts
- * const svg = '<svg><circle cx="50" cy="50" r="40"/></svg>';
- * const base64 = svgToBase64(svg);
- * // Use in data URL: `data:image/svg+xml;base64,${base64}`
- * ```
- */
-declare const svgToBase64: (str: string) => string;
-/**
- * Pauses execution for the specified time.
- *
- * `signal` allows cancelling the sleep via AbortSignal.
- *
- * @param time - Time in milliseconds to sleep (default is 1000ms)
- * @param signal - Optional AbortSignal to cancel the sleep early
- * @returns - A Promise that resolves after the specified time or when aborted
- */
-declare const sleep: (time?: number, signal?: AbortSignal) => Promise<void>;
-type DebouncedFunction<F extends (...args: any[]) => any> = {
-  (...args: Parameters<F>): ReturnType<F> | undefined;
-  readonly isPending: boolean;
-};
-/**
- * Creates a debounced function that delays invoking the provided function until
- * after the specified `wait` time has elapsed since the last invocation.
- *
- * If the `immediate` option is set to `true`, the function will be invoked immediately
- * on the leading edge of the wait interval. Subsequent calls during the wait interval
- * will reset the timer but not invoke the function until the interval elapses again.
- *
- * The returned function includes the `isPending` property to check if the debounce
- * timer is currently active.
- *
- * @typeParam F - The type of the function to debounce.
- *
- * @param function_ - The function to debounce.
- * @param wait - The number of milliseconds to delay (default is 100ms).
- * @param options - An optional object with the following properties:
- *   - `immediate` (boolean): If `true`, invokes the function on the leading edge
- *     of the wait interval instead of the trailing edge.
- *
- * @returns A debounced version of the provided function, enhanced with the `isPending` property.
- *
- * @throws {TypeError} If the first parameter is not a function.
- * @throws {RangeError} If the `wait` parameter is negative.
- *
- * @example
- * ```ts
- * // Basic debouncing
- * const log = debounce((message: string) => console.log(message), 200);
- * log('Hello'); // Logs "Hello" after 200ms if no other call is made.
- * console.log(log.isPending); // true if the timer is active.
- *
- * // Immediate execution
- * const save = debounce(() => saveToServer(), 500, { immediate: true });
- * save(); // Executes immediately, then waits 500ms for subsequent calls
- *
- * // Check pending state
- * const debouncedSearch = debounce(searchAPI, 300);
- * debouncedSearch('query');
- * if (debouncedSearch.isPending) {
- *   showLoadingIndicator();
- * }
- * ```
- */
-declare function debounce<F extends (...args: any[]) => any>(function_: F, wait?: number, options?: {
-  immediate: boolean;
-}): DebouncedFunction<F>;
-type ThrottledFunction<F extends (...args: any[]) => any> = {
-  (...args: Parameters<F>): ReturnType<F> | undefined;
-  readonly isPending: boolean;
-};
-/**
- * Creates a throttled function that invokes the provided function at most once
- * every `wait` milliseconds.
- *
- * If the `leading` option is set to `true`, the function will be invoked immediately
- * on the leading edge of the throttle interval. If the `trailing` option is set to `true`,
- * the function will also be invoked at the end of the throttle interval if additional
- * calls were made during the interval.
- *
- * The returned function includes the `isPending` property to check if the throttle
- * timer is currently active.
- *
- * @typeParam F - The type of the function to throttle.
- *
- * @param function_ - The function to throttle.
- * @param wait - The number of milliseconds to wait between invocations (default is 100ms).
- * @param options - An optional object with the following properties:
- *   - `leading` (boolean): If `true`, invokes the function on the leading edge of the interval.
- *   - `trailing` (boolean): If `true`, invokes the function on the trailing edge of the interval.
- *
- * @returns A throttled version of the provided function, enhanced with the `isPending` property.
- *
- * @throws {TypeError} If the first parameter is not a function.
- * @throws {RangeError} If the `wait` parameter is negative.
- *
- * @example
- * ```ts
- * // Basic throttling (leading edge by default)
- * const log = throttle((message: string) => console.log(message), 200);
- * log('Hello'); // Logs "Hello" immediately
- * log('World'); // Ignored for 200ms
- * console.log(log.isPending); // true if within throttle window
- *
- * // Trailing edge only
- * const trailingLog = throttle(() => console.log('trailing'), 200, {
- *   leading: false,
- *   trailing: true
- * });
- * trailingLog(); // No immediate execution
- * // After 200ms: logs "trailing"
- *
- * // Both edges
- * const bothLog = throttle(() => console.log('both'), 200, {
- *   leading: true,
- *   trailing: true
- * });
- * bothLog(); // Immediate execution
- * // After 200ms: executes again if called during window
- * ```
- */
-declare function throttle<F extends (...args: any[]) => any>(function_: F, wait?: number, options?: {
-  leading?: boolean;
-  trailing?: boolean;
-}): ThrottledFunction<F>;
-/**
- * Formats a string by replacing each '%s' placeholder with the corresponding argument.
- *
- * Mimics the basic behavior of C's printf for %s substitution. Supports both
- * variadic arguments and array-based argument passing. Extra placeholders
- * are left as-is, missing arguments result in empty strings.
- *
- * @param format - The format string containing '%s' placeholders.
- * @param args - The values to substitute, either as separate arguments or a single array.
- * @returns The formatted string with placeholders replaced by arguments.
- *
- * @example
- * ```ts
- * // Basic usage with separate arguments
- * printf("%s love %s", "I", "Bangladesh") // "I love Bangladesh"
- *
- * // Using array of arguments
- * printf("%s love %s", ["I", "Bangladesh"]) // "I love Bangladesh"
- *
- * // Extra placeholders remain unchanged
- * printf("%s %s %s", "Hello", "World") // "Hello World %s"
- *
- * // Missing arguments become empty strings
- * printf("%s and %s", "this") // "this and "
- *
- * // Multiple occurrences
- * printf("%s %s %s", "repeat", "repeat", "repeat") // "repeat repeat repeat"
- * ```
- */
-declare function printf(format: string, ...args: unknown[]): string;
-/**
- * Merges multiple refs into a single ref callback.
- *
- * @param refs - An array of refs to merge.
- * @returns - A function that updates the merged ref with the provided value.
- *
- * @example
- * ```tsx
- * const MyComponent = () => {
- *   const ref1 = useRef<HTMLDivElement>(null);
- *   const ref2 = useRef<HTMLDivElement>(null);
- *
- *   const mergedRef = mergeRefs(ref1, ref2);
- *
- *   return <div ref={mergedRef}>Content</div>;
- * };
- * ```
- */
-type MergeRefs = <T>(...refs: Array<React.Ref<T> | undefined>) => React.RefCallback<T>;
-declare const mergeRefs: MergeRefs;
-/**
- * Navigates to the specified client-side hash without triggering SSR.
- *
- * Smoothly scrolls to an element by ID and updates the URL hash.
- * Use `scroll-margin-top` CSS property to add margins for fixed headers.
- *
- * @param id - The ID of the element (without #) to navigate to.
- * @param opts - Additional options for scrollIntoView.
- *
- * @example
- * ```ts
- * // Navigate to an element
- * goToClientSideHash('section-about');
- *
- * // With custom scroll behavior
- * goToClientSideHash('contact', { behavior: 'auto', block: 'center' });
- * ```
- */
-declare function goToClientSideHash(id: string, opts?: ScrollIntoViewOptions): void;
-/**
- * Escapes a string for use in a regular expression.
- *
- * @param str - The string to escape
- * @returns - The escaped string safe for use in RegExp constructor
- *
- * @example
- * ```ts
- * const escapedString = escapeRegExp('Hello, world!');
- * // escapedString === 'Hello\\, world!'
- *
- * const regex = new RegExp(escapeRegExp(userInput));
- * ```
- */
-declare function escapeRegExp(str: string): string;
-/**
- * Normalizes a string by:
- * - Applying Unicode normalization (NFC)
- * - Optionally removing diacritic marks (accents)
- * - Optionally trimming leading/trailing non-alphanumeric characters
- * - Optionally converting to lowercase
- *
- * @param str - The string to normalize
- * @param options - Normalization options
- * @param options.lowercase - Whether to convert the result to lowercase (default: true)
- * @param options.removeAccents - Whether to remove diacritic marks like accents (default: true)
- * @param options.removeNonAlphanumeric - Whether to trim non-alphanumeric characters from the edges (default: true)
- * @returns The normalized string
- *
- * @example
- * ```ts
- * normalizeText('Café') // 'cafe'
- * normalizeText('  Hello!  ') // 'hello'
- * normalizeText('José', { removeAccents: false }) // 'josé'
- * ```
- */
-declare function normalizeText(str?: string | null, options?: {
-  lowercase?: boolean;
-  removeAccents?: boolean;
-  removeNonAlphanumeric?: boolean;
-}): string;
-//#endregion
-//#region src/functions/worker.d.ts
-/**
- * Converts a regular function into a workerized version that runs in a Web Worker.
- *
- * This provides the ultimate DX for Web Workers - just write a normal function
- * and "workerize" it to run in the background without blocking the UI.
- *
- * @param fn - The function to workerize
- * @returns A function that calls the original function in a worker and returns a Promise
- *
- * @example
- * ```ts
- * // Define a normal function
- * function fibonacci(n: number): number {
- *   if (n <= 1) return n;
- *   return fibonacci(n - 1) + fibonacci(n - 2);
- * }
- *
- * // Workerize it
- * const workerizedFib = workerize(fibonacci);
- *
- * // Use like a normal async function!
- * const result = await workerizedFib(35);
- * console.log(result); // Works just like the original function
- * ```
- *
- * @example
- * ```ts
- * // Works with any function signature
- * const sumArray = workerize((arr: number[]) =>
- *   arr.reduce((a, b) => a + b, 0)
- * );
- *
- * const result = await sumArray([1, 2, 3, 4, 5]); // 15
- * ```
- */
-declare function workerize<T extends (...args: any[]) => any>(fn: T): (...args: Parameters<T>) => Promise<ReturnType<T>>;
-//#endregion
-export { deepmerge as A, Task as C, getObjectValue as D, extendProps as E, getClientSideCookie as M, hasClientSideCookie as N, hydrate as O, setClientSideCookie as P, ScheduleOpts as S, poll as T, scrollTo as _, convertToNormalCase as a, throttle as b, debounce as c, isLinkActive as d, isNavActive as f, printf as g, normalizeText as h, cn as i, deleteClientSideCookie as j, DeepMergeOptions as k, escapeRegExp as l, mergeRefs as m, MergeRefs as n, convertToSlug as o, isSSR as p, cleanSrc as r, copyToClipboard as s, workerize as t, goToClientSideHash as u, sleep as v, schedule as w, shield as x, svgToBase64 as y };