@sohanemon/utils 6.2.7 → 6.2.10

package/dist/functions/hydrate.js

@@ -1,31 +0,0 @@
-import { isPlainObject } from '../types';
-/**
- * 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
- * hydrate({ a: null, b: 'test' }) // { a: undefined, b: 'test' }
- * hydrate([null, 1, { c: null }]) // [undefined, 1, { c: undefined }]
- */
-export function hydrate(data) {
-    return convertNulls(data);
-}
-function convertNulls(value) {
-    if (value === null)
-        return undefined;
-    if (typeof value !== 'object' || value === null)
-        return value;
-    if (Array.isArray(value)) {
-        return value.map(convertNulls);
-    }
-    if (isPlainObject(value)) {
-        const result = {};
-        for (const key in value) {
-            result[key] = convertNulls(value[key]);
-        }
-        return result;
-    }
-    return value;
-}

package/dist/functions/index.d.ts

@@ -1,8 +0,0 @@
-export * from './cookie';
-export * from './deepmerge';
-export * from './hydrate';
-export * from './object';
-export * from './poll';
-export * from './schedule';
-export * from './shield';
-export * from './utils';

package/dist/functions/index.js

@@ -1,8 +0,0 @@
-export * from './cookie';
-export * from './deepmerge';
-export * from './hydrate';
-export * from './object';
-export * from './poll';
-export * from './schedule';
-export * from './shield';
-export * from './utils';

package/dist/functions/object.d.ts

@@ -1,93 +0,0 @@
-/**
- * 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 extends Array<string | number>> = K 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
- */
-export declare function getObjectValue<T, K extends Array<string | number>, D>(obj: T, path: K, defaultValue: D): Exclude<GetValue<T, K>, 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
- */
-export declare function getObjectValue<T, K extends Array<string | number>>(obj: T, path: K): GetValue<T, K> | 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
- */
-export 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
- */
-export 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.
- *
- * @template T The base object or function type
- * @template P The additional properties type
- *
- * @param base - The object or function to extend
- * @param props - An object containing properties to attach
- *
- * @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 }
- */
-export declare function extendProps<T extends object, P extends object>(base: T, props: P): T & P;
-export {};

package/dist/functions/object.js

@@ -1,67 +0,0 @@
-/**
- * Implementation of deep object value retrieval with type safety
- * @param obj - Source object
- * @param path - Path specification (string or array)
- * @param defaultValue - Optional fallback value
- * @returns Value at path or default/undefined
- */
-export function getObjectValue(obj, path, defaultValue) {
-    // Validate path type and handle edge cases
-    if (typeof path !== 'string' && !Array.isArray(path)) {
-        return defaultValue;
-    }
-    // Ensure pathArray is always an array
-    const pathArray = (() => {
-        if (Array.isArray(path))
-            return path;
-        if (path === '')
-            return [];
-        return String(path)
-            .split('.')
-            .filter((segment) => segment !== '');
-    })();
-    // Final safety check for array type
-    if (!Array.isArray(pathArray)) {
-        return defaultValue;
-    }
-    let current = obj;
-    for (const key of pathArray) {
-        if (current === null || current === undefined) {
-            return defaultValue;
-        }
-        // Convert numeric strings to numbers for arrays
-        const actualKey = typeof key === 'string' && Array.isArray(current) && /^\d+$/.test(key)
-            ? Number.parseInt(key, 10)
-            : key;
-        current = current[actualKey];
-    }
-    return current !== undefined ? current : defaultValue;
-}
-/**
- * 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.
- *
- * @template T The base object or function type
- * @template P The additional properties type
- *
- * @param base - The object or function to extend
- * @param props - An object containing properties to attach
- *
- * @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 }
- */
-export function extendProps(base, props) {
-    return Object.assign(base, props);
-}

package/dist/functions/poll.d.ts

@@ -1,38 +0,0 @@
-/**
- * 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
- * const job = await poll(async () => {
- *   const status = await getJobStatus();
- *   return status === 'done' ? status : null;
- * }, { interval: 3000, timeout: 60000 });
- * ```
- */
-export 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>;

package/dist/functions/poll.js

@@ -1,69 +0,0 @@
-import { sleep } from './utils';
-/**
- * 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
- * const job = await poll(async () => {
- *   const status = await getJobStatus();
- *   return status === 'done' ? status : null;
- * }, { interval: 3000, timeout: 60000 });
- * ```
- */
-export async function poll(cond, { interval = 5000, timeout = 5 * 60 * 1000, jitter = true, signal, } = {}) {
-    const start = Date.now();
-    let aborted = signal?.aborted ?? false;
-    // fast listener (avoids repeated property lookups)
-    const abortListener = () => {
-        aborted = true;
-    };
-    signal?.addEventListener('abort', abortListener, { once: true });
-    try {
-        for (let attempt = 0;; attempt++) {
-            // fast exit check
-            if (aborted)
-                throw new Error('Polling aborted');
-            const result = await cond();
-            if (result)
-                return result;
-            const elapsed = Date.now() - start;
-            if (elapsed >= timeout)
-                throw new Error('Polling timed out', {
-                    cause: `Polling timed out after ${timeout}ms`,
-                });
-            // add jitter (±10%) for anti-sync
-            const delay = jitter
-                ? interval + (Math.random() - 0.5) * interval * 0.2
-                : interval;
-            await sleep(delay, signal);
-        }
-    }
-    catch (err) {
-        throw err; // stop polling on any error
-    }
-    finally {
-        // cleanup to avoid leaks
-        signal?.removeEventListener('abort', abortListener);
-    }
-}

package/dist/functions/schedule.d.ts

@@ -1,12 +0,0 @@
-export type Task = () => Promise<void> | void;
-export interface ScheduleOpts {
-    retry?: number;
-    delay?: number;
-    timeout?: number;
-}
-/**
- * Runs a function asynchronously in the background.
- * Returns immediately, retries on failure if configured.
- * Logs total time taken.
- */
-export declare function schedule(task: Task, options?: ScheduleOpts): void;

package/dist/functions/schedule.js

@@ -1,29 +0,0 @@
-/**
- * Runs a function asynchronously in the background.
- * Returns immediately, retries on failure if configured.
- * Logs total time taken.
- */
-export function schedule(task, options = {}) {
-    const { retry = 0, delay = 0 } = options;
-    const start = Date.now();
-    const attempt = async (triesLeft) => {
-        try {
-            await task();
-            const total = Date.now() - start;
-            console.log(`⚡[schedule.ts] Completed in ${total}ms`);
-        }
-        catch (err) {
-            console.log('⚡[schedule.ts] err:', err);
-            if (triesLeft > 0) {
-                console.log(`⚡[schedule.ts] Retrying in ${delay}ms...`);
-                setTimeout(() => attempt(triesLeft - 1), delay);
-            }
-            else {
-                const total = Date.now() - start;
-                console.log(`⚡[schedule.ts] Failed after ${total}ms`);
-            }
-        }
-    };
-    // Schedule immediately
-    setTimeout(() => attempt(retry), 0);
-}

package/dist/functions/shield.d.ts

@@ -1,18 +0,0 @@
-/**
- * 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
- * const [err, value] = shield(() => riskySync());
- * if (err) console.error(err);
- *
- * const [asyncErr, result] = await shield(fetchData());
- * if (asyncErr) throw asyncErr;
- * ```
- */
-export declare function shield<T, E = Error>(operation: Promise<T>): Promise<[E | null, T | null]>;
-export declare function shield<T, E = Error>(operation: () => T): [E | null, T | null];

package/dist/functions/shield.js

@@ -1,15 +0,0 @@
-export function shield(operation) {
-    if (operation instanceof Promise) {
-        return operation
-            .then((value) => [null, value])
-            .catch((error) => [error, null]);
-    }
-    try {
-        const data = operation();
-        return [null, data];
-    }
-    catch (error) {
-        console.log(`\x1b[31m🛡 [shield]\x1b[0m ${operation.name} failed →`, error);
-        return [error, null];
-    }
-}

package/dist/functions/utils.d.ts

@@ -1,243 +0,0 @@
-import { type ClassValue } from 'clsx';
-import type * as React from 'react';
-/**
- * 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.
- */
-export 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.
- */
-export 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.
- */
-export 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.
- *
- * @param  src - The source path to clean.
- * @returns - The cleaned path.
- */
-export 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.
- */
-export declare const scrollTo: (containerSelector: string | React.RefObject<HTMLDivElement>, to: "top" | "bottom") => void;
-/**
- * Copies a given string to the clipboard.
- *
- * @param  value - The value to copy to the clipboard.
- * @param  [onSuccess=() => {}] - Optional callback executed after successful copy.
- */
-export declare const copyToClipboard: (value: string, onSuccess?: () => void) => void;
-/**
- * Converts camelCase, PascalCase, kebab-case, snake_case into normal case.
- *
- * @param  inputString - The string need to be converted into normal case
- * @returns - Normal Case
- */
-export 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"
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export 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
- * 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.
- */
-export 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
- * 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.
- */
-export 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.
- * 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)`.
- *
- * @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.
- *
- * @example
- * ```ts
- * const message = printf("%s love %s", "I", "Bangladesh");
- * // message === "I love Bangladesh"
- *
- * const arr = ["I", "Bangladesh"];
- * const message2 = printf("%s love %s", arr);
- * // message2 === "I love Bangladesh"
- *
- * // If there are too few arguments:
- * const incomplete = printf("Bangladesh is %s %s", "beautiful");
- * // incomplete === "Bangladesh is beautiful"
- * ```
- */
-export 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.
- */
-export type MergeRefs = <T>(...refs: Array<React.Ref<T> | undefined>) => React.RefCallback<T>;
-export declare const mergeRefs: MergeRefs;
-/**
- * Navigates to the specified client-side hash without ssr.
- * use `scroll-margin-top` with css to add margins
- *
- * @param id - The ID of the element without # to navigate to.
- *
- * @example goToClientSideHash('my-element');
- */
-export 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
- *
- * @example
- * const escapedString = escapeRegExp('Hello, world!');
- * // escapedString === 'Hello\\, world!'
- */
-export 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
- */
-export declare function normalizeText(str?: string | null, options?: {
-    lowercase?: boolean;
-    removeAccents?: boolean;
-    removeNonAlphanumeric?: boolean;
-}): string;
-export {};