@sohanemon/utils 6.3.8 → 6.4.0

package/dist/index.d.cts

@@ -1,11 +1,63 @@
-import { n as Task, r as schedule, t as ScheduleOpts } from "./schedule-CRsY0oqG.cjs";
+import { n as Task, r as schedule, t as ScheduleOpts } from "./schedule-BqFAJlSO.cjs";
 import * as React from "react";
 import { ClassValue } from "clsx";
 
 //#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;
 };
@@ -41,20 +93,52 @@ type TMerged<T> = [T] extends [Array<any>] ? { [K in keyof T]: TMerged<T[K]> } :
  * @returns The merged object with proper typing
  *
  * @example
- * // Basic merge
+ * // Basic shallow merge
  * deepmerge({ a: 1 }, { b: 2 }) // { a: 1, b: 2 }
  *
  * @example
- * // Nested merge
- * deepmerge({ a: { x: 1 } }, { a: { y: 2 } }) // { a: { x: 1, y: 2 } }
+ * // 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 concat
- * deepmerge({ arr: [1] }, { arr: [2] }, { arrayMerge: 'concat' }) // { arr: [1, 2] }
+ * // Array replacement (default)
+ * deepmerge({ items: [1, 2] }, { items: [3, 4] })
+ * // { items: [3, 4] }
  *
  * @example
- * // Sources with extra properties
- * deepmerge({ a: 1 }, { b: 2, c: 3 }) // { a: 1, b: 2, c: 3 }
+ * // 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' }] }
  */
 declare function deepmerge<T extends Record<string, any>, S$1 extends Record<string, any>[]>(target: T, ...sources: S$1): TMerged<T | S$1[number]>;
 declare function deepmerge<T extends Record<string, any>, S$1 extends Record<string, any>[]>(target: T, sources: S$1, options?: {
@@ -73,8 +157,42 @@ type Hydrate<T> = T extends null ? undefined : T extends (infer U)[] ? Hydrate<U
  * @returns Same type as input, but with all nulls replaced by undefined
  *
  * @example
- * hydrate({ a: null, b: 'test' }) // { a: undefined, b: 'test' }
- * hydrate([null, 1, { c: null }]) // [undefined, 1, { c: undefined }]
+ * ```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
@@ -158,14 +276,32 @@ declare function getObjectValue<T, S$1 extends string>(obj: T, path: S$1): GetVa
  * @returns The same object/function, augmented with the given properties
  *
  * @example
- * // Extend an object
- * const obj = extendProps({ a: 1 }, { b: "hello" });
- * // obj has { a: number; b: string }
- *
- * // Extend a function
- * const fn = (x: number) => x * 2;
- * const enhanced = extendProps(fn, { name: "doubler" });
- * // enhanced is callable and also has { name: string }
+ * ```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
+ * });
+ * ```
  */
 declare function extendProps<T extends object, P$1 extends object>(base: T, props: P$1): T & P$1;
 //#endregion
@@ -196,11 +332,52 @@ declare function extendProps<T extends object, P$1 extends object>(base: T, prop
  *
  * @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,
@@ -224,11 +401,62 @@ declare function poll<T>(cond: () => Promise<T | null | false | undefined>, {
  *
  * @example
  * ```ts
- * const [err, value] = shield(() => riskySync());
- * if (err) console.error(err);
+ * // 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;
+ * }
+ * ```
  *
- * const [asyncErr, result] = await shield(fetchData());
- * if (asyncErr) throw asyncErr;
+ * @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]>;
@@ -240,6 +468,12 @@ declare function shield<T, E = Error>(operation: () => T): [E | null, T | null];
  *
  * @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;
 /**
@@ -250,16 +484,40 @@ declare function cn(...inputs: ClassValue[]): string;
  * @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.
  *
- * @param {Object} params - Parameters object.
- * @param {string} params.path - The target path of the link.
- * @param {string} params.currentPath - The current browser path.
- * @param {string[]} [params.locales=['en', 'es', 'de', 'zh', 'bn', 'fr', 'it', 'nl']] - Supported locale prefixes.
- * @returns {boolean} - True if the link is active, false otherwise.
+ * 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,
@@ -275,29 +533,74 @@ declare function isLinkActive({
 /**
  * Cleans a file path by removing the `/public/` prefix if present.
  *
- * @param  src - The source path to clean.
- * @returns - The cleaned path.
+ * 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.
  *
- * @param  containerSelector - The CSS selector or React ref for the container.
- * @param  to - Specifies whether to scroll to the top or bottom.
+ * 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.
+ * Copies a given string to the clipboard using the modern Clipboard API.
  *
- * @param  value - The value to copy to the clipboard.
- * @param  [onSuccess=() => {}] - Optional callback executed after successful copy.
+ * 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 camelCase, PascalCase, kebab-case, snake_case into normal case.
+ * Converts various case styles (camelCase, PascalCase, kebab-case, snake_case) into readable normal case.
  *
- * @param  inputString - The string need to be converted into normal case
- * @returns - 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;
 /**
@@ -314,6 +617,17 @@ 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;
 /**
@@ -321,6 +635,13 @@ declare const isSSR: boolean;
  *
  * @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;
 /**
@@ -362,9 +683,23 @@ type DebouncedFunction<F$1 extends (...args: any[]) => any> = {
  * @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$1 extends (...args: any[]) => any>(function_: F$1, wait?: number, options?: {
   immediate: boolean;
@@ -399,9 +734,29 @@ type ThrottledFunction<F$1 extends (...args: any[]) => any> = {
  * @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 if leading is true.
- * console.log(log.isPending); // true if the timer is active.
+ * 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$1 extends (...args: any[]) => any>(function_: F$1, wait?: number, options?: {
   leading?: boolean;
@@ -409,26 +764,31 @@ declare function throttle<F$1 extends (...args: any[]) => any>(function_: F$1, w
 }): ThrottledFunction<F$1>;
 /**
  * Formats a string by replacing each '%s' placeholder with the corresponding argument.
- * This function mimics the basic behavior of C's printf for %s substitution.
  *
- * It supports both calls like `printf(format, ...args)` and `printf(format, argsArray)`.
+ * 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 into the placeholders, either as separate arguments or as a single array.
- * @returns The formatted string with all '%s' replaced by the provided arguments.
+ * @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
- * const message = printf("%s love %s", "I", "Bangladesh");
- * // message === "I love Bangladesh"
+ * // 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"
  *
- * const arr = ["I", "Bangladesh"];
- * const message2 = printf("%s love %s", arr);
- * // message2 === "I love Bangladesh"
+ * // Missing arguments become empty strings
+ * printf("%s and %s", "this") // "this and "
  *
- * // If there are too few arguments:
- * const incomplete = printf("Bangladesh is %s %s", "beautiful");
- * // incomplete === "Bangladesh is beautiful"
+ * // Multiple occurrences
+ * printf("%s %s %s", "repeat", "repeat", "repeat") // "repeat repeat repeat"
  * ```
  */
 declare function printf(format: string, ...args: unknown[]): string;
@@ -436,29 +796,54 @@ 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 ssr.
- * use `scroll-margin-top` with css to add margins
+ * Navigates to the specified client-side hash without triggering SSR.
  *
- * @param id - The ID of the element without # to navigate to.
+ * Smoothly scrolls to an element by ID and updates the URL hash.
+ * Use `scroll-margin-top` CSS property to add margins for fixed headers.
  *
- * @example goToClientSideHash('my-element');
+ * @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
+ * @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;
 /**
@@ -474,6 +859,13 @@ declare function escapeRegExp(str: string): string;
  * @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;
@@ -482,31 +874,422 @@ declare function normalizeText(str?: string | null, options?: {
 }): string;
 //#endregion
 //#region src/types/utilities.d.ts
+/**
+ * Extracts the keys of an object type as a union type.
+ *
+ * @template T - The object type to extract keys from
+ * @returns A union of all keys in the object type
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number };
+ * type UserKeys = Keys<User>; // 'name' | 'age'
+ * ```
+ */
 type Keys<T extends object> = keyof T;
+/**
+ * Extracts the values of an object type as a union type.
+ *
+ * @template T - The object type to extract values from
+ * @returns A union of all values in the object type
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number };
+ * type UserValues = Values<User>; // string | number
+ * ```
+ */
 type Values<T extends object> = T[keyof T];
+/**
+ * Makes all properties of an object type optional recursively.
+ *
+ * This type traverses through nested objects and arrays, making all properties optional.
+ * Functions and primitives are left unchanged.
+ *
+ * @template T - The type to make deeply partial
+ * @returns A type with all properties optional recursively
+ *
+ * @example
+ * ```ts
+ * type Config = {
+ *   server: { host: string; port: number };
+ *   features: string[];
+ * };
+ *
+ * type PartialConfig = DeepPartial<Config>;
+ * // {
+ * //   server?: { host?: string; port?: number };
+ * //   features?: string[];
+ * // }
+ * ```
+ */
 type DeepPartial<T> = T extends Function ? T : T extends Array<infer U> ? Array<DeepPartial<U>> : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+/**
+ * Makes only specified properties of an object type optional.
+ *
+ * @template T - The base object type
+ * @template K - The keys to make optional
+ * @returns An object type with specified properties optional
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number; email: string };
+ * type PartialUser = SelectivePartial<User, 'age' | 'email'>;
+ * // { name: string; age?: number; email?: string }
+ * ```
+ */
 type SelectivePartial<T, K$1 extends keyof T> = Omit<T, K$1> & Partial<Pick<T, K$1>>;
+/**
+ * Makes all properties of an object type required recursively.
+ *
+ * This type traverses through nested objects and arrays, making all properties required.
+ * Functions and primitives are left unchanged.
+ *
+ * @template T - The type to make deeply required
+ * @returns A type with all properties required recursively
+ *
+ * @example
+ * ```ts
+ * type PartialConfig = {
+ *   server?: { host?: string; port?: number };
+ * };
+ *
+ * type RequiredConfig = DeepRequired<PartialConfig>;
+ * // {
+ * //   server: { host: string; port: number };
+ * // }
+ * ```
+ */
 type DeepRequired<T> = T extends Function ? T : T extends Array<infer U> ? Array<DeepRequired<U>> : T extends object ? { [K in keyof T]-?: DeepRequired<T[K]> } : T;
+/**
+ * Makes only specified properties of an object type required.
+ *
+ * @template T - The base object type
+ * @template K - The keys to make required
+ * @returns An object type with specified properties required
+ *
+ * @example
+ * ```ts
+ * type PartialUser = { name?: string; age?: number; email?: string };
+ * type RequiredUser = SelectiveRequired<PartialUser, 'name'>;
+ * // { name: string; age?: number; email?: string }
+ * ```
+ */
 type SelectiveRequired<T, K$1 extends keyof T> = Omit<T, K$1> & Required<Pick<T, K$1>>;
+/**
+ * Creates a type where all properties are never (useful for excluding types).
+ *
+ * This can be used to create mutually exclusive types or to exclude certain properties.
+ *
+ * @template T - The object type to transform
+ * @returns An object type with all properties set to never
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number };
+ * type ExcludedUser = Never<User>; // { name: never; age: never }
+ * ```
+ */
 type Never<T> = { [K in keyof T]: never };
+/**
+ * Makes all properties of an object type nullable recursively.
+ *
+ * @template T - The type to make nullable
+ * @returns A type where all properties can be null
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; profile: { age: number } };
+ * type NullableUser = Nullable<User>;
+ * // { name: string | null; profile: { age: number | null } | null }
+ * ```
+ */
 type Nullable<T> = T extends object ? { [P in keyof T]: Nullable<T[P]> } : T | null;
+/**
+ * Makes all properties of an object type optional (undefined) recursively.
+ *
+ * @template T - The type to make optional
+ * @returns A type where all properties can be undefined
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; profile: { age: number } };
+ * type OptionalUser = Optional<User>;
+ * // { name: string | undefined; profile: { age: number | undefined } | undefined }
+ * ```
+ */
 type Optional<T> = T extends object ? { [P in keyof T]: Optional<T[P]> } : T | undefined;
+/**
+ * Makes all properties of an object type nullish (null or undefined) recursively.
+ *
+ * @template T - The type to make nullish
+ * @returns A type where all properties can be null or undefined
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; profile: { age: number } };
+ * type NullishUser = Nullish<User>;
+ * // { name: string | null | undefined; profile: { age: number | null | undefined } | null | undefined }
+ * ```
+ */
 type Nullish<T> = T extends object ? { [P in keyof T]: Nullish<T[P]> } : T | null | undefined;
+/**
+ * Makes all properties of an object type optional and nullish recursively.
+ *
+ * This combines optional properties with nullish values.
+ *
+ * @template T - The type to make maybe
+ * @returns A type where all properties are optional and can be null or undefined
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; profile: { age: number } };
+ * type MaybeUser = Maybe<User>;
+ * // { name?: string | null | undefined; profile?: { age?: number | null | undefined } | null | undefined }
+ * ```
+ */
 type Maybe<T> = T extends object ? { [P in keyof T]?: Nullish<T[P]> } : T | null | undefined;
+/**
+ * Makes all properties of an object type readonly recursively.
+ *
+ * This type traverses through nested objects and arrays, making all properties readonly.
+ * Functions and primitives are left unchanged.
+ *
+ * @template T - The type to make deeply readonly
+ * @returns A type with all properties readonly recursively
+ *
+ * @example
+ * ```ts
+ * type Config = {
+ *   server: { host: string; port: number };
+ *   features: string[];
+ * };
+ *
+ * type ReadonlyConfig = DeepReadonly<Config>;
+ * // {
+ * //   readonly server: { readonly host: string; readonly port: number };
+ * //   readonly features: readonly string[];
+ * // }
+ * ```
+ */
 type DeepReadonly<T> = T extends Function ? T : T extends Array<infer U> ? ReadonlyArray<DeepReadonly<U>> : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
+/**
+ * Removes readonly modifier from all properties of an object type recursively.
+ *
+ * @template T - The readonly type to make mutable
+ * @returns A type with all readonly modifiers removed
+ *
+ * @example
+ * ```ts
+ * type ReadonlyUser = { readonly name: string; readonly profile: { readonly age: number } };
+ * type MutableUser = Mutable<ReadonlyUser>;
+ * // { name: string; profile: { age: number } }
+ * ```
+ */
 type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+/**
+ * Extracts keys of an object type that have values of a specific type.
+ *
+ * @template T - The object type to search
+ * @template U - The value type to match
+ * @returns A union of keys whose values match the specified type
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number; active: boolean };
+ * type StringKeys = KeysOfType<User, string>; // 'name'
+ * type NumberKeys = KeysOfType<User, number>; // 'age'
+ * ```
+ */
 type KeysOfType<T, U$1> = { [K in keyof T]: T[K] extends U$1 ? K : never }[keyof T];
+/**
+ * Omits properties from an object type that have values of a specific type.
+ *
+ * @template T - The object type to filter
+ * @template U - The value type to exclude
+ * @returns An object type without properties of the specified value type
+ *
+ * @example
+ * ```ts
+ * type Mixed = { name: string; age: number; active: boolean };
+ * type WithoutStrings = OmitByType<Mixed, string>; // { age: number; active: boolean }
+ * ```
+ */
 type OmitByType<T, U$1> = { [K in keyof T as T[K] extends U$1 ? never : K]: T[K] };
+/**
+ * Makes specified properties required while keeping others as-is.
+ *
+ * @template T - The base object type
+ * @template K - The keys to make required
+ * @returns An object type with specified properties required
+ *
+ * @example
+ * ```ts
+ * type PartialUser = { name?: string; age?: number; email?: string };
+ * type RequiredNameUser = RequiredKeys<PartialUser, 'name'>;
+ * // { name: string; age?: number; email?: string }
+ * ```
+ */
 type RequiredKeys<T, K$1 extends keyof T> = Omit<T, K$1> & Required<Pick<T, K$1>>;
+/**
+ * Computes the symmetric difference between two object types.
+ *
+ * Properties that exist in either T or U but not in both.
+ *
+ * @template T - First object type
+ * @template U - Second object type
+ * @returns Properties unique to T or U
+ *
+ * @example
+ * ```ts
+ * type A = { x: number; y: string };
+ * type B = { y: string; z: boolean };
+ * type DiffAB = Diff<A, B>; // { x: number; z: boolean }
+ * ```
+ */
 type Diff<T, U$1> = Omit<T, keyof U$1> & Omit<U$1, keyof T>;
+/**
+ * Computes the intersection of two object types (properties present in both).
+ *
+ * @template T - First object type
+ * @template U - Second object type
+ * @returns Properties that exist in both T and U
+ *
+ * @example
+ * ```ts
+ * type A = { x: number; y: string };
+ * type B = { y: string; z: boolean };
+ * type IntersectionAB = Intersection<A, B>; // { y: string }
+ * ```
+ */
 type Intersection<T extends object, U$1 extends object> = Pick<T, Extract<keyof T, keyof U$1> & Extract<keyof U$1, keyof T>>;
+/**
+ * Merges two object types, combining their properties.
+ *
+ * @template T - First object type
+ * @template U - Second object type
+ * @returns A merged object type with properties from both
+ *
+ * @example
+ * ```ts
+ * type A = { x: number; y: string };
+ * type B = { y: boolean; z: string };
+ * type Merged = Merge<A, B>; // { x: number; y: boolean; z: string }
+ * ```
+ */
 type Merge<T extends object, U$1 extends object, I = Diff<T, U$1> & Intersection<U$1, T> & Diff<U$1, T>> = Pick<I, keyof I>;
+/**
+ * Subtracts properties of one object type from another.
+ *
+ * @template T - The object type to subtract from
+ * @template U - The object type whose properties to subtract
+ * @returns T without properties that exist in U
+ *
+ * @example
+ * ```ts
+ * type A = { x: number; y: string; z: boolean };
+ * type B = { y: string };
+ * type Subtracted = Substract<A, B>; // { x: number; z: boolean }
+ * ```
+ */
 type Substract<T extends object, U$1 extends object> = Omit<T, keyof U$1>;
+/**
+ * Represents either all properties present or none of them.
+ *
+ * Useful for creating mutually exclusive configurations.
+ *
+ * @template T - The object type
+ * @returns Either the full object or an empty object with optional properties
+ *
+ * @example
+ * ```ts
+ * type Config = { host: string; port: number };
+ * type AllOrNoneConfig = AllOrNone<Config>;
+ * // { host: string; port: number } | {}
+ * ```
+ */
 type AllOrNone<T> = T | { [P in keyof T]?: never };
+/**
+ * Represents exactly one property from an object type being present.
+ *
+ * Useful for creating discriminated unions or mutually exclusive options.
+ *
+ * @template T - The object type
+ * @returns A union where only one property is present at a time
+ *
+ * @example
+ * ```ts
+ * type Action = { type: 'create'; payload: string } | { type: 'update'; id: number };
+ * type OneAction = OneOf<Action>;
+ * // { type: 'create'; payload: string } | { type: 'update'; id: number }
+ * ```
+ */
 type OneOf<T> = { [K in keyof T]: Pick<T, K> }[keyof T];
+/**
+ * Represents exactly two properties from an object type being present.
+ *
+ * @template T - The object type
+ * @returns A union where exactly two properties are present at a time
+ *
+ * @example
+ * ```ts
+ * type Config = { a: number; b: string; c: boolean };
+ * type TwoConfig = TwoOf<Config>;
+ * // { a: number; b: string } | { a: number; c: boolean } | { b: string; c: boolean }
+ * ```
+ */
 type TwoOf<T> = { [K in keyof T]: { [L in Exclude<keyof T, K>]: Pick<T, K | L> }[Exclude<keyof T, K>] }[keyof T];
+/**
+ * Prettifies a complex type by expanding it for better readability in tooltips.
+ *
+ * This type doesn't change the runtime type but helps with IntelliSense display.
+ *
+ * @template T - The type to prettify
+ * @returns The same type but expanded for better readability
+ *
+ * @example
+ * ```ts
+ * type Complex = { a: string } & { b: number };
+ * type PrettyComplex = Prettify<Complex>; // Shows as { a: string; b: number }
+ * ```
+ */
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
+/**
+ * Extracts all nested keys of an object type as dot-separated strings.
+ *
+ * @template ObjectType - The object type to extract nested keys from
+ * @template IgnoreKeys - Keys to ignore during extraction
+ * @returns A union of dot-separated string paths
+ *
+ * @example
+ * ```ts
+ * type User = {
+ *   name: string;
+ *   profile: { age: number; address: { city: string } };
+ *   tags: string[];
+ * };
+ *
+ * type UserPaths = NestedKeyOf<User>;
+ * // 'name' | 'profile' | 'profile.age' | 'profile.address' | 'profile.address.city' | 'tags'
+ * ```
+ */
 type NestedKeyOf<ObjectType extends object, IgnoreKeys extends string = never> = { [Key in keyof ObjectType & string]: Key extends IgnoreKeys ? never : ObjectType[Key] extends object ? ObjectType[Key] extends Array<any> ? Key : `${Key}` | `${Key}.${NestedKeyOf<ObjectType[Key], IgnoreKeys>}` : `${Key}` }[keyof ObjectType & string];
+/**
+ * Creates a type that excludes properties present in another type.
+ *
+ * This is useful for creating mutually exclusive types.
+ *
+ * @template T - The base type
+ * @template U - The type whose properties to exclude
+ * @returns A type with properties from T that are not in U
+ *
+ * @example
+ * ```ts
+ * type A = { x: number; y: string };
+ * type B = { y: string };
+ * type WithoutB = Without<A, B>; // { x?: never }
+ * ```
+ */
 type Without<T, U$1> = { [P in Exclude<keyof T, keyof U$1>]?: never };
 //#endregion
 //#region src/types/gates.d.ts
@@ -642,11 +1425,61 @@ type NAND<T extends any[]> = NOT<AND<T>>;
 type NOR<T extends any[]> = NOT<OR<T>>;
 //#endregion
 //#region src/types/guards.d.ts
+/**
+ * Represents primitive JavaScript types including null and undefined.
+ */
 type Primitive = string | number | bigint | boolean | symbol | null | undefined;
+/**
+ * Represents all falsy values in JavaScript.
+ */
 type Falsy = false | '' | 0 | null | undefined;
+/**
+ * Type guard that checks if a value is falsy.
+ *
+ * @param val - The value to check
+ * @returns True if the value is falsy, false otherwise
+ *
+ * @example
+ * if (isFalsy(value)) {
+ *   console.log('Value is falsy');
+ * }
+ */
 declare const isFalsy: (val: unknown) => val is Falsy;
+/**
+ * Type guard that checks if a value is null or undefined.
+ *
+ * @param val - The value to check
+ * @returns True if the value is null or undefined, false otherwise
+ *
+ * @example
+ * if (isNullish(value)) {
+ *   console.log('Value is null or undefined');
+ * }
+ */
 declare const isNullish: (val: unknown) => val is null | undefined;
+/**
+ * Type guard that checks if a value is a primitive type.
+ *
+ * @param val - The value to check
+ * @returns True if the value is a primitive, false otherwise
+ *
+ * @example
+ * if (isPrimitive(value)) {
+ *   console.log('Value is a primitive type');
+ * }
+ */
 declare const isPrimitive: (val: unknown) => val is Primitive;
+/**
+ * Type guard that checks if a value is a plain object (not an array, function, etc.).
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object, false otherwise
+ *
+ * @example
+ * if (isPlainObject(value)) {
+ *   console.log('Value is a plain object');
+ * }
+ */
 declare function isPlainObject(value: unknown): value is Record<string, any>;
 //#endregion
 export { AND, AllOrNone, BUFFER, DeepPartial, DeepReadonly, DeepRequired, Diff, Falsy, IMPLIES, Intersection, Keys, KeysOfType, Maybe, Merge, MergeRefs, Mutable, NAND, NOR, NOT, NestedKeyOf, Never, Nullable, Nullish, OR, OmitByType, OneOf, Optional, Prettify, Primitive, RequiredKeys, ScheduleOpts, SelectivePartial, SelectiveRequired, Substract, Task, TwoOf, Values, Without, XNOR, XNOR_Binary, XOR, XOR_Binary, cleanSrc, cn, convertToNormalCase, convertToSlug, copyToClipboard, debounce, deepmerge, deleteClientSideCookie, escapeRegExp, extendProps, getClientSideCookie, getObjectValue, goToClientSideHash, hasClientSideCookie, hydrate, isFalsy, isLinkActive, isNavActive, isNullish, isPlainObject, isPrimitive, isSSR, mergeRefs, normalizeText, poll, printf, schedule, scrollTo, setClientSideCookie, shield, sleep, svgToBase64, throttle };