@sohanemon/utils 5.2.8 → 6.2.0

package/README.md

@@ -3,22 +3,23 @@
 ![npm version](https://img.shields.io/npm/v/@sohanemon/utils)
 ![npm downloads](https://img.shields.io/npm/dm/@sohanemon/utils)
 ![License](https://img.shields.io/npm/l/@sohanemon/utils)
+![Tests](https://github.com/sohanemon/sohanemon-utils/actions/workflows/test.yml/badge.svg)
 
 ## Description
 
-`sohanemon/utils` is a collection of utility functions and hooks designed to simplify common tasks in modern web development. It includes utilities for handling objects, cookies, class name merging, and more. The library is built with TypeScript and is fully typed, ensuring a smooth and error-free development experience.
+`sohanemon/utils` is a comprehensive collection of utility functions, hooks, components, and types designed to simplify common tasks in modern web development. It includes utilities for object manipulation, async operations, scheduling, data transformation, React hooks for state management and effects, UI components, and advanced TypeScript types. The library is built with TypeScript and is fully typed, ensuring a smooth and error-free development experience.
 
 ## Features
 
-- **Object Utilities**: Functions to manipulate and access nested object properties.
+- **Object Utilities**: Functions to access and manipulate nested object properties, extend objects, and more.
+- **Data Transformation**: Deep merging, null-to-undefined conversion, slug generation, text normalization, and more.
+- **Async Operations**: Polling, scheduling, debouncing, throttling, and safe async execution.
 - **Cookie Management**: Functions to set, get, delete, and check for cookies.
 - **Class Name Merging**: A utility to merge class names with Tailwind CSS and custom logic.
-- **Responsive Media Queries**: Hooks to detect media queries based on Tailwind CSS breakpoints.
-- **Debounce and Throttle**: Utilities to control the rate of function execution.
-- **Copy to Clipboard**: A hook to copy text to the clipboard and track the copy status.
-- **Local Storage Management**: A hook to persist state in local storage.
-- **URL Parameter Management**: A hook to manage URL parameters as state.
-- **DOM Calculation**: Hooks to calculate dimensions of elements based on viewport and other block dimensions.
+- **React Hooks**: Hooks for media queries, effects, state management (local/session storage, URL params), DOM calculations, async operations, scheduling, and more.
+- **UI Components**: React components for HTML injection, media wrapping, responsive indicators, scrollable markers, and Iconify icons.
+- **TypeScript Types**: Advanced utility types for deep partials, requireds, readonly, guards, and type-level logic gates.
+- **Browser Utilities**: Clipboard operations, scroll management, SSR detection, and more.
 
 ## Installation
 
@@ -38,17 +39,20 @@ yarn add @sohanemon/utils
 
 ### Importing Utilities
 
-You can import individual utilities or hooks as needed:
+You can import individual utilities, hooks, components, or types as needed:
 
-```javascript
-import { cn, getObjectValue, setClientSideCookie } from '@sohanemon/utils';
+```typescript
+import { cn, getObjectValue, setClientSideCookie, hydrate, poll } from '@sohanemon/utils';
+import { useAsync, useLocalStorage } from '@sohanemon/utils';
+import { HtmlInjector, ResponsiveIndicator } from '@sohanemon/utils';
+import type { DeepPartial, Primitive } from '@sohanemon/utils';
 ```
 
 ### Examples
 
 #### Class Name Merging
 
-```javascript
+```typescript
 import { cn } from '@sohanemon/utils';
 
 const className = cn('bg-blue-500', 'text-white', 'p-4', 'rounded-lg');
@@ -56,118 +60,102 @@ const className = cn('bg-blue-500', 'text-white', 'p-4', 'rounded-lg');
 
 #### Object Utilities
 
-```javascript
-import { getObjectValue } from '@sohanemon/utils';
+```typescript
+import { getObjectValue, extendProps } from '@sohanemon/utils';
 
 const obj = { a: { b: { c: 1 } } };
 const value = getObjectValue(obj, 'a.b.c'); // 1
+
+const extended = extendProps({ a: 1 }, { b: 'hello' }); // { a: 1, b: 'hello' }
 ```
 
-#### Cookie Management
+#### Data Transformation
 
-```javascript
-import { setClientSideCookie, getClientSideCookie } from '@sohanemon/utils';
+```typescript
+import { hydrate, convertToSlug, normalizeText } from '@sohanemon/utils';
 
-setClientSideCookie('username', 'sohanemon', 7);
-const { value } = getClientSideCookie('username'); // 'sohanemon'
+const cleaned = hydrate({ a: null, b: { c: null } }); // { a: undefined, b: { c: undefined } }
+const slug = convertToSlug('Hello World!'); // 'hello-world'
+const normalized = normalizeText('Café', { removeAccents: true }); // 'cafe'
 ```
 
-#### Responsive Media Queries
+#### Async Operations
 
-```javascript
-import { useMediaQuery } from '@sohanemon/utils';
+```typescript
+import { poll, shield, sleep } from '@sohanemon/utils';
 
-const isMobile = useMediaQuery('sm');
+const result = await poll(async () => {
+  const status = await checkStatus();
+  return status === 'ready' ? status : null;
+}, { interval: 2000, timeout: 30000 });
+
+const [error, data] = await shield(fetchData());
+```
+
+#### Cookie Management
+
+```typescript
+import { setClientSideCookie, getClientSideCookie } from '@sohanemon/utils';
+
+setClientSideCookie('username', 'sohanemon', 7);
+const { value } = getClientSideCookie('username'); // 'sohanemon'
 ```
 
 #### Debounce and Throttle
 
-```javascript
+```typescript
 import { debounce, throttle } from '@sohanemon/utils';
 
 const debouncedFunction = debounce(() => console.log('Debounced!'), 300);
 const throttledFunction = throttle(() => console.log('Throttled!'), 300);
 ```
 
-#### Copy to Clipboard
-
-```javascript
-import { useCopyToClipboard } from '@sohanemon/utils/hooks';
-
-const { isCopied, copy } = useCopyToClipboard();
+#### React Hooks
 
-return (
-  <div>
-    <button onClick={() => copy('Hello, World!')}>Copy</button>
-    {isCopied && <span>Copied!</span>}
-  </div>
-);
-```
+```typescript
+import { useAsync, useLocalStorage, useMediaQuery, useCopyToClipboard } from '@sohanemon/utils';
 
-#### Local Storage Management
+const { data, isLoading } = useAsync(async (signal) => {
+  return await fetchData(signal);
+}, { mode: 'auto' });
 
-```javascript
-import { useLocalStorage } from '@sohanemon/utils/hooks';
+const [value, setValue] = useLocalStorage('key', { count: 0 });
 
-const [value, setValue] = useLocalStorage('myKey', 'initialValue');
+const isMobile = useMediaQuery('sm');
 
-return (
-  <div>
-    <input
-      type="text"
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-    />
-  </div>
-);
+const { isCopied, copy } = useCopyToClipboard();
 ```
 
-#### URL Parameter Management
-
-```javascript
-import { useUrlParams } from '@sohanemon/utils/hooks';
+#### UI Components
 
-const [param, setParam] = useUrlParams('myParam', 'defaultValue');
+```tsx
+import { HtmlInjector, ResponsiveIndicator, Iconify } from '@sohanemon/utils';
 
-return (
-  <div>
-    <input
-      type="text"
-      value={param}
-      onChange={(e) => setParam(e.target.value)}
-    />
-  </div>
-);
+<HtmlInjector html="<p>Injected HTML</p>" />
+<ResponsiveIndicator />
+<Iconify icon="mdi:home" />
 ```
 
-#### DOM Calculation
+#### TypeScript Types
 
-```javascript
-import { useDomCalculation } from '@sohanemon/utils/hooks';
-
-const { height, width } = useDomCalculation({
-  blockIds: ['header', 'footer'],
-  margin: 20,
-  substract: true,
-});
+```typescript
+import type { DeepPartial, Nullable, KeysOfType } from '@sohanemon/utils';
 
-return (
-  <div style={{ height, width }}>
-    Content
-  </div>
-);
+type PartialUser = DeepPartial<User>;
+type NullableUser = Nullable<User>;
+type StringKeys = KeysOfType<User, string>;
 ```
 
 ## API Documentation
 
-### Class Name Merging
+### Functions
 
+#### Class Name Merging
 ```typescript
 cn(...inputs: ClassValue[]): string
 ```
 
-### Object Utilities
-
+#### Object Utilities
 ```typescript
 getObjectValue<T, K extends Array<string | number>, D>(
   obj: T,
@@ -190,26 +178,63 @@ getObjectValue<T, S extends string>(
   obj: T,
   path: S
 ): GetValue<T, SplitPath<S>> | undefined;
-```
 
-### Cookie Management
+extendProps<T extends object, P extends object>(
+  base: T,
+  props: P
+): T & P;
+```
 
+#### Data Transformation
 ```typescript
-setClientSideCookie(name: string, value: string, days?: number, path?: string): void
-deleteClientSideCookie(name: string, path?: string): void
-hasClientSideCookie(name: string): boolean
-getClientSideCookie(name: string): { value: string | undefined }
-```
+hydrate<T>(data: T): Hydrate<T>
 
-### Responsive Media Queries
+deepmerge<T, U>(
+  target: T,
+  source: U,
+  options?: {
+    arrayMerge?: (target: any[], source: any[]) => any[];
+    maxDepth?: number;
+  }
+): T & U
 
-```typescript
-useMediaQuery(tailwindBreakpoint: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | `(${string})`): boolean
-```
+convertToSlug(str: string): string
 
-### Debounce and Throttle
+normalizeText(
+  str?: string | null,
+  options?: {
+    lowercase?: boolean;
+    removeAccents?: boolean;
+    removeNonAlphanumeric?: boolean;
+  }
+): string
 
+convertToNormalCase(inputString: string): string
+
+escapeRegExp(str: string): string
+
+printf(format: string, ...args: unknown[]): string
+```
+
+#### Async & Scheduling
 ```typescript
+poll<T>(
+  cond: () => Promise<T | null | false | undefined>,
+  options?: {
+    interval?: number;
+    timeout?: number;
+    signal?: AbortSignal;
+    jitter?: boolean;
+  }
+): Promise<T>
+
+schedule(task: Task, options?: ScheduleOpts): void
+
+shield<T, E = Error>(operation: Promise<T>): Promise<[E | null, T | null]>
+shield<T, E = Error>(operation: () => T): [E | null, T | null]
+
+sleep(time?: number, signal?: AbortSignal): Promise<void>
+
 debounce<F extends (...args: any[]) => any>(
   function_: F,
   wait?: number,
@@ -223,39 +248,231 @@ throttle<F extends (...args: any[]) => any>(
 ): ThrottledFunction<F>
 ```
 
-### Copy to Clipboard
+#### Cookie Management
+```typescript
+setClientSideCookie(name: string, value: string, days?: number, path?: string): void
+deleteClientSideCookie(name: string, path?: string): void
+hasClientSideCookie(name: string): boolean
+getClientSideCookie(name: string): { value: string | undefined }
+```
 
+#### Browser Utilities
 ```typescript
-useCopyToClipboard({ timeout?: number }): { isCopied: boolean; copy: (value: string) => void }
+copyToClipboard(value: string, onSuccess?: () => void): void
+
+scrollTo(
+  containerSelector: string | React.RefObject<HTMLDivElement>,
+  to: 'top' | 'bottom'
+): void
+
+goToClientSideHash(id: string, opts?: ScrollIntoViewOptions): void
+
+isSSR: boolean
+
+svgToBase64(str: string): string
+
+isLinkActive(options: {
+  path: string;
+  currentPath: string;
+  locales?: string[];
+  exact?: boolean;
+}): boolean
+
+isNavActive(href: string, path: string): boolean // deprecated
+
+cleanSrc(src: string): string
 ```
 
-### Local Storage Management
+### React Hooks
 
+#### State & Effects
 ```typescript
-useLocalStorage<T extends Record<string, any>>(key: string, defaultValue: T): LocalStorageValue<T>
+useAction<Input, Result>(
+  action: ActionType<Input, Result>,
+  options?: UseActionOptions<Input, Result>
+): {
+  execute: (input: Input) => void;
+  executeAsync: (input: Input) => Promise<Result>;
+  reset: () => void;
+  useExecute: (input: Input) => void;
+  data: Result | null;
+  error: Error | null;
+  input: Input | undefined;
+  isIdle: boolean;
+  isLoading: boolean;
+  isSuccess: boolean;
+  isError: boolean;
+}
+
+useAsync<TData, TError extends Error = Error>(
+  asyncFn: (signal: AbortSignal) => Promise<TData>,
+  options?: UseAsyncOptions<TData, TError>
+): UseAsyncReturn<TData, TError>
+
+useLocalStorage<T extends Record<string, any>>(
+  key: string,
+  defaultValue: T
+): [T, React.Dispatch<React.SetStateAction<T>>]
+
+useSessionStorage<T extends Record<string, any>>(
+  key: string,
+  defaultValue: T
+): [T, React.Dispatch<React.SetStateAction<T>>]
+
+useUrlParams<T extends string | number | boolean>(
+  key: string,
+  defaultValue: T
+): [T, (value: T) => void]
+
+useDebounce<T>(state: T, delay?: number): T
+
+useTimeout(callback: () => void, delay?: number | null): void
+
+useEffectOnce(effect: React.EffectCallback): void
+
+useUpdateEffect(effect: React.EffectCallback, deps: React.DependencyList): void
+
+useIsomorphicEffect: typeof React.useLayoutEffect | typeof React.useEffect
 ```
 
-### URL Parameter Management
+#### UI & Interaction
+```typescript
+useMediaQuery(tailwindBreakpoint: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | `(${string})`): boolean
+
+useClickOutside(callback: () => void): React.RefObject<HTMLDivElement>
+
+useCopyToClipboard(options?: { timeout?: number }): {
+  isCopied: boolean;
+  copy: (value: string) => void;
+}
+
+useWindowEvent<K extends keyof WindowEventMap>(
+  type: K,
+  listener: (this: Window, ev: WindowEventMap[K]) => void,
+  options?: boolean | AddEventListenerOptions
+): void
 
+useQuerySelector<T extends Element>(selector: string): T | null
+
+useIsClient(): boolean
+
+useLockScroll(): void
+
+useIntersection(options?: UseIntersectionOptions): {
+  ref: React.RefObject<Element>;
+  isIntersecting: boolean;
+}
+
+useIsScrolling(): {
+  isScrolling: boolean;
+  scrollableContainerRef: React.RefObject<HTMLElement>;
+}
+
+useIsAtTop(options?: { offset?: number }): {
+  scrollableContainerRef: React.RefObject<HTMLElement>;
+  isAtTop: boolean;
+}
+```
+
+#### DOM & Layout
+```typescript
+useDomCalculation(options: CalculationProps): { height: number; width: number }
+
+useHeightCalculation(options: CalculationProps2): number
+```
+
+#### Scheduling
 ```typescript
-useUrlParams<T extends string | number | boolean>(key: string, defaultValue: T): [T, (value: T) => void]
+useSchedule(options?: ScheduleOpts): (task: Task) => void
+
+useScheduledEffect(
+  effect: () => void | (() => void),
+  deps?: React.DependencyList,
+  options?: ScheduleOpts
+): void
 ```
 
-### DOM Calculation
+### Components
+
+```typescript
+Iconify: React.Component (from @iconify/react)
+
+HtmlInjector: React.Component<{ html: string; className?: string }>
+
+MediaWrapper: React.Component<{
+  src: string;
+  alt?: string;
+  className?: string;
+  lazy?: boolean;
+}>
+
+ResponsiveIndicator: React.Component<{
+  className?: string;
+  showText?: boolean;
+}>
+
+ScrollableMarker: React.Component<{
+  className?: string;
+  children?: React.ReactNode;
+}>
+```
+
+### Types
+
+#### Utility Types
+```typescript
+Keys<T extends object>: keyof T
+Values<T extends object>: T[keyof T]
+DeepPartial<T>: T with all properties optional recursively
+SelectivePartial<T, K>: T with selected keys optional
+DeepRequired<T>: T with all properties required recursively
+SelectiveRequired<T, K>: T with selected keys required
+Never<T>: Object with never values
+Nullable<T>: T with null added to primitives
+Optional<T>: T with undefined added to primitives
+Nullish<T>: T with null|undefined added to primitives
+Maybe<T>: T with all properties optional and nullish
+DeepReadonly<T>: T with all properties readonly recursively
+Mutable<T>: T with readonly removed
+KeysOfType<T, U>: Keys of T where value is U
+OmitByType<T, U>: T without properties of type U
+RequiredKeys<T, K>: T with selected keys required
+Diff<T, U>: Properties in T or U but not both
+Intersection<T, U>: Common properties
+Merge<T, U>: Merged object
+Substract<T, U>: T without U properties
+AllOrNone<T>: T or empty object
+OneOf<T>: Union of single property objects
+TwoOf<T>: Union of two property objects
+Prettify<T>: Clean type representation
+NestedKeyOf<T>: All nested keys as strings
+Without<T, U>: T without U keys
+```
+
+#### Type Guards & Primitives
+```typescript
+Primitive: string | number | bigint | boolean | symbol | null | undefined
+Falsy: false | '' | 0 | null | undefined
+
+isFalsy(val: unknown): val is Falsy
+isNullish(val: unknown): val is null | undefined
+isPrimitive(val: unknown): val is Primitive
+isPlainObject(value: unknown): value is Record<string, any>
+```
 
+#### Logic Gates
 ```typescript
-useDomCalculation({
-  blockIds: string[];
-  dynamic?: boolean | string;
-  margin?: number;
-  substract?: boolean;
-  onChange?: (results: {
-    blocksHeight: number;
-    blocksWidth: number;
-    remainingWidth: number;
-    remainingHeight: number;
-  }) => void;
-}): { height: number; width: number }
+BUFFER<T>: T
+IMPLIES<T, U>: true if T extends U
+XOR_Binary<T, U>: T | U with exclusions
+XNOR_Binary<T, U>: T & U | neither
+AND<T extends any[]>: All true
+OR<T extends any[]>: At least one true
+XOR<T extends any[]>: Odd number true
+XNOR<T extends any[]>: Even number true
+NOT<T>: Never properties
+NAND<T extends any[]>: NOT AND
+NOR<T extends any[]>: NOT OR
 ```
 
 ## Contributing

package/dist/functions/deepmerge.d.ts

@@ -0,0 +1,59 @@
+type TAllKeys<T> = T extends any ? keyof T : never;
+type TIndexValue<T, K extends PropertyKey, D = never> = T extends any ? K extends keyof T ? T[K] : D : never;
+type TPartialKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>> 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 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.arrayMerge - How to merge arrays: 'replace' (default), 'concat', or 'merge'
+ * @param options.clone - Whether to clone the target (default: true)
+ * @param options.customMerge - Custom merge function for specific keys
+ * @param options.maxDepth - Maximum recursion depth (default: 100)
+ * @returns The merged object with proper typing
+ *
+ * @example
+ * // Basic 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 } }
+ *
+ * @example
+ * // Array concat
+ * deepmerge({ arr: [1] }, { arr: [2] }, { arrayMerge: 'concat' }) // { arr: [1, 2] }
+ *
+ * @example
+ * // Sources with extra properties
+ * deepmerge({ a: 1 }, { b: 2, c: 3 }) // { a: 1, b: 2, c: 3 }
+ */
+export declare function deepmerge<T extends Record<string, any>, S extends Record<string, any>[]>(target: T, ...sources: S): TMerged<T | S[number]>;
+export declare function deepmerge<T extends Record<string, any>, S extends Record<string, any>[]>(target: T, sources: S, options?: {
+    arrayMerge?: 'replace' | 'concat' | 'merge' | ((target: any[], source: any[]) => any[]);
+    clone?: boolean;
+    customMerge?: (key: string | symbol, targetValue: any, sourceValue: any) => any;
+    maxDepth?: number;
+}): TMerged<T | S[number]>;
+export {};

package/dist/functions/deepmerge.js

@@ -0,0 +1,116 @@
+import { isPlainObject } from '../types';
+export function deepmerge(target, ...args) {
+    let sources;
+    let options = {};
+    // Check if last arg is options object
+    const lastArg = args[args.length - 1];
+    if (lastArg &&
+        typeof lastArg === 'object' &&
+        !Array.isArray(lastArg) &&
+        (lastArg.arrayMerge !== undefined ||
+            lastArg.clone !== undefined ||
+            lastArg.customMerge !== undefined ||
+            lastArg.maxDepth !== undefined)) {
+        options = { ...options, ...lastArg };
+        sources = args.slice(0, -1);
+    }
+    else {
+        sources = args;
+    }
+    const { arrayMerge = 'replace', clone = true, customMerge, maxDepth = 100, } = options;
+    const visited = new WeakMap();
+    return mergeObjects(target, sources, 0);
+    function mergeObjects(target, sources, depth) {
+        if (depth >= maxDepth) {
+            console.warn(`[deepmerge] Maximum depth ${maxDepth} exceeded. Returning target as-is.`);
+            return target;
+        }
+        if (!isPlainObject(target) && !Array.isArray(target)) {
+            // For primitives or special objects, return the last source or target
+            for (const source of sources) {
+                if (source !== undefined)
+                    return source;
+            }
+            return target;
+        }
+        let result = clone
+            ? Array.isArray(target)
+                ? [...target]
+                : { ...target }
+            : target;
+        for (const source of sources) {
+            if (source == null)
+                continue;
+            if (visited.has(source)) {
+                // Circular reference, skip
+                continue;
+            }
+            visited.set(source, result);
+            if (Array.isArray(result) && Array.isArray(source)) {
+                result = mergeArrays(result, source, arrayMerge);
+            }
+            else if (isPlainObject(result) && isPlainObject(source)) {
+                const keys = new Set([
+                    ...Object.keys(result),
+                    ...Object.keys(source),
+                    ...Object.getOwnPropertySymbols(result),
+                    ...Object.getOwnPropertySymbols(source),
+                ]);
+                for (const key of keys) {
+                    const targetValue = result[key];
+                    const sourceValue = source[key];
+                    if (customMerge &&
+                        customMerge(key, targetValue, sourceValue) !== undefined) {
+                        result[key] = customMerge(key, targetValue, sourceValue);
+                    }
+                    else if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+                        result[key] = mergeObjects(targetValue, [sourceValue], depth + 1);
+                    }
+                    else if (Array.isArray(targetValue) && Array.isArray(sourceValue)) {
+                        result[key] = mergeArrays(targetValue, sourceValue, arrayMerge);
+                    }
+                    else if (sourceValue !== undefined) {
+                        result[key] = sourceValue;
+                    }
+                }
+            }
+            else {
+                // If types don't match, source takes precedence
+                result = source;
+            }
+        }
+        return result;
+    }
+    function mergeArrays(target, source, strategy) {
+        if (typeof strategy === 'function') {
+            return strategy(target, source);
+        }
+        switch (strategy) {
+            case 'concat':
+                return [...target, ...source];
+            case 'merge':
+                const maxLength = Math.max(target.length, source.length);
+                const merged = [];
+                for (let i = 0; i < maxLength; i++) {
+                    if (i < target.length && i < source.length) {
+                        if (isPlainObject(target[i]) && isPlainObject(source[i])) {
+                            merged[i] = mergeObjects(target[i], [source[i]], 0);
+                        }
+                        else {
+                            merged[i] = source[i];
+                        }
+                    }
+                    else if (i < target.length) {
+                        merged[i] = target[i];
+                    }
+                    else {
+                        merged[i] = source[i];
+                    }
+                }
+                return merged;
+            case 'replace':
+            default:
+                return [...source];
+        }
+    }
+}

package/dist/functions/hydrate.d.ts

@@ -1,46 +1,15 @@
-import { DeepNullToUndefined } from '../types/utilities';
+type Hydrate<T> = T extends null ? undefined : T extends (infer U)[] ? Hydrate<U>[] : T extends object ? {
+    [K in keyof T]: Hydrate<T[K]>;
+} : T;
 /**
- * Deeply cleans any value by converting all `null` values to `undefined`,
- * and merges in a fallback object for default values.
- *
- * Features:
- * - Circular reference detection to prevent infinite loops
- * - Proper handling of special objects (Date, Map, Set, RegExp, etc.)
- * - Strict type safety with improved generics
- * - Better error messages and validation
- * - Support for nested structures with Symbol properties
- * - Optional maximum recursion depth to prevent stack overflow
- * - Configurable null-to-undefined conversion
+ * Converts all `null` values to `undefined` in the data structure recursively.
  *
  * @param data - Any input data (object, array, primitive)
- * @param fallback - Optional fallback values to merge with
- * @param options - Configuration options
- * @param options.maxDepth - Maximum recursion depth (default: 100)
- * @param options.throwOnCircular - Whether to throw on circular refs (default: false)
- * @param options.convertNullToUndefined - Convert null to undefined (default: true)
  * @returns Same type as input, but with all nulls replaced by undefined
  *
- * @throws {TypeError} If data or fallback are invalid types when strict validation is enabled
- * @throws {RangeError} If circular reference detected and throwOnCircular is true
- *
  * @example
- * // Basic usage
  * hydrate({ a: null, b: 'test' }) // { a: undefined, b: 'test' }
- *
- * @example
- * // With fallback values
- * hydrate({ a: null }, { a: 'default' }) // { a: 'default' }
- *
- * @example
- * // Keep nulls as-is
- * hydrate({ a: null }, undefined, { convertNullToUndefined: false }) // { a: null }
- */
-export declare function hydrate<T>(data: T, fallback?: Partial<T>, options?: {
-    maxDepth?: number;
-    throwOnCircular?: boolean;
-    convertNullToUndefined?: boolean;
-}): DeepNullToUndefined<T>;
-/**
- * Type guard utility for checking if a value is an object with a specific shape
+ * hydrate([null, 1, { c: null }]) // [undefined, 1, { c: undefined }]
  */
-export declare function isWithFallbackCompatible<T extends object>(value: unknown): value is T;
+export declare function hydrate<T>(data: T): Hydrate<T>;
+export {};

package/dist/functions/hydrate.js

@@ -1,155 +1,31 @@
+import { isPlainObject } from '../types';
 /**
- * Deeply cleans any value by converting all `null` values to `undefined`,
- * and merges in a fallback object for default values.
- *
- * Features:
- * - Circular reference detection to prevent infinite loops
- * - Proper handling of special objects (Date, Map, Set, RegExp, etc.)
- * - Strict type safety with improved generics
- * - Better error messages and validation
- * - Support for nested structures with Symbol properties
- * - Optional maximum recursion depth to prevent stack overflow
- * - Configurable null-to-undefined conversion
+ * Converts all `null` values to `undefined` in the data structure recursively.
  *
  * @param data - Any input data (object, array, primitive)
- * @param fallback - Optional fallback values to merge with
- * @param options - Configuration options
- * @param options.maxDepth - Maximum recursion depth (default: 100)
- * @param options.throwOnCircular - Whether to throw on circular refs (default: false)
- * @param options.convertNullToUndefined - Convert null to undefined (default: true)
  * @returns Same type as input, but with all nulls replaced by undefined
  *
- * @throws {TypeError} If data or fallback are invalid types when strict validation is enabled
- * @throws {RangeError} If circular reference detected and throwOnCircular is true
- *
  * @example
- * // Basic usage
  * hydrate({ a: null, b: 'test' }) // { a: undefined, b: 'test' }
- *
- * @example
- * // With fallback values
- * hydrate({ a: null }, { a: 'default' }) // { a: 'default' }
- *
- * @example
- * // Keep nulls as-is
- * hydrate({ a: null }, undefined, { convertNullToUndefined: false }) // { a: null }
+ * hydrate([null, 1, { c: null }]) // [undefined, 1, { c: undefined }]
  */
-export function hydrate(data, fallback, options) {
-    const maxDepth = options?.maxDepth ?? 100;
-    const throwOnCircular = options?.throwOnCircular ?? false;
-    const convertNullToUndefined = options?.convertNullToUndefined ?? true;
-    // Use WeakSet for O(1) circular reference detection
-    const visited = new WeakSet();
-    return processValue(data, fallback, 0, visited);
-    function processValue(value, fallbackValue, depth, visited) {
-        // Check recursion depth
-        if (depth > maxDepth) {
-            console.warn(`[hydrate] Maximum recursion depth (${maxDepth}) exceeded. Returning value as-is.`);
-            return (value ?? fallbackValue);
-        }
-        if (value === null) {
-            return (convertNullToUndefined ? undefined : (fallbackValue ?? null));
-        }
-        // Handle undefined - use fallback or return undefined
-        if (value === undefined) {
-            return (fallbackValue ?? undefined);
-        }
-        // Handle primitives: string, number, boolean, symbol, bigint
-        const type = typeof value;
-        if (type !== 'object') {
-            return value;
-        }
-        if (visited.has(value)) {
-            if (throwOnCircular) {
-                throw new RangeError('[hydrate] Circular reference detected');
-            }
-            // Return the value as-is to break the cycle
-            return value;
-        }
-        // Mark as visited to detect circular references
-        visited.add(value);
-        if (isSpecialObject(value)) {
-            return handleSpecialObject(value, fallbackValue);
-        }
-        // Handle arrays
-        if (Array.isArray(value)) {
-            const fallbackArray = Array.isArray(fallbackValue)
-                ? fallbackValue
-                : undefined;
-            return value.map((item, index) => processValue(item, fallbackArray?.[index], depth + 1, visited));
-        }
-        // Handle plain objects
-        if (isPlainObject(value)) {
-            const fallbackObj = isPlainObject(fallbackValue)
-                ? fallbackValue
-                : {};
-            const result = { ...fallbackObj };
-            // Process all enumerable properties including symbols
-            const keys = [
-                ...Object.keys(value),
-                ...Object.getOwnPropertySymbols(value),
-            ];
-            for (const k of keys) {
-                const propValue = value[k];
-                const fallbackProp = fallbackObj[k];
-                result[k] = processValue(propValue, fallbackProp, depth + 1, visited);
-            }
-            return result;
-        }
-        // For other objects, return as-is (instances, etc.)
-        return (value ?? fallbackValue);
-    }
+export function hydrate(data) {
+    return convertNulls(data);
 }
-/**
- * Checks if a value is a plain object (not a special type)
- */
-function isPlainObject(value) {
-    if (typeof value !== 'object' || value === null) {
-        return false;
-    }
-    if (Object.prototype.toString.call(value) !== '[object Object]') {
-        return false;
+function convertNulls(value) {
+    if (value === null)
+        return undefined;
+    if (typeof value !== 'object' || value === null)
+        return value;
+    if (Array.isArray(value)) {
+        return value.map(convertNulls);
     }
-    // Objects with null prototype are still plain objects
-    const proto = Object.getPrototypeOf(value);
-    return proto === null || proto === Object.prototype;
-}
-/**
- * Checks if a value is a special object type that needs custom handling
- */
-function isSpecialObject(value) {
-    if (typeof value !== 'object' || value === null) {
-        return false;
+    if (isPlainObject(value)) {
+        const result = {};
+        for (const key in value) {
+            result[key] = convertNulls(value[key]);
+        }
+        return result;
     }
-    const stringTag = Object.prototype.toString.call(value);
-    const specialTypes = [
-        '[object Date]',
-        '[object RegExp]',
-        '[object Map]',
-        '[object Set]',
-        '[object WeakMap]',
-        '[object WeakSet]',
-        '[object Promise]',
-        '[object Error]',
-        '[object ArrayBuffer]',
-    ];
-    return specialTypes.includes(stringTag);
-}
-/**
- * Handles special object types that shouldn't be deeply cloned
- */
-function handleSpecialObject(value, fallbackValue) {
-    // For special types, return the original value or fallback
-    // These shouldn't be deeply cloned as they have internal state
-    return value ?? fallbackValue;
-}
-/**
- * Type guard utility for checking if a value is an object with a specific shape
- */
-export function isWithFallbackCompatible(value) {
-    return (typeof value === 'object' &&
-        (value === null ||
-            Array.isArray(value) ||
-            (typeof value === 'object' &&
-                Object.prototype.toString.call(value) === '[object Object]')));
+    return value;
 }

package/dist/functions/index.d.ts

@@ -1,4 +1,5 @@
 export * from './cookie';
+export * from './deepmerge';
 export * from './hydrate';
 export * from './object';
 export * from './poll';

package/dist/functions/index.js

@@ -1,4 +1,5 @@
 export * from './cookie';
+export * from './deepmerge';
 export * from './hydrate';
 export * from './object';
 export * from './poll';

package/dist/functions/utils.js

@@ -427,7 +427,7 @@ export function normalizeText(str, options = {}) {
     const { lowercase = true, removeAccents = true, removeNonAlphanumeric = true, } = options;
     let result = str.normalize('NFC');
     if (removeAccents) {
-        result = result.replace(/\p{M}/gu, ''); // remove accents
+        result = result.normalize('NFD').replace(/\p{M}/gu, ''); // decompose and remove accents
     }
     if (removeNonAlphanumeric) {
         result = result.replace(/^[^\p{L}\p{N}]*|[^\p{L}\p{N}]*$/gu, ''); // trim edges

package/dist/types/guards.d.ts

@@ -3,3 +3,4 @@ export type Falsy = false | '' | 0 | null | undefined;
 export declare const isFalsy: (val: unknown) => val is Falsy;
 export declare const isNullish: (val: unknown) => val is null | undefined;
 export declare const isPrimitive: (val: unknown) => val is Primitive;
+export declare function isPlainObject(value: unknown): value is Record<string, any>;

package/dist/types/guards.js

@@ -16,3 +16,14 @@ export const isPrimitive = (val) => {
             return false;
     }
 };
+export function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (Object.prototype.toString.call(value) !== '[object Object]') {
+        return false;
+    }
+    // Objects with null prototype are still plain objects
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}

package/dist/types/utilities.d.ts

@@ -7,10 +7,7 @@ export type SelectivePartial<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T
 export 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;
-export type NullToUndefined<T> = T extends null ? undefined : T;
-export type DeepNullToUndefined<T> = T extends Function ? T : T extends Array<infer U> ? Array<DeepNullToUndefined<U>> : T extends object ? {
-    [K in keyof T]: DeepNullToUndefined<NullToUndefined<T[K]>>;
-} : NullToUndefined<T>;
+export type SelectiveRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
 export type Never<T> = {
     [K in keyof T]: never;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sohanemon/utils",
-  "version": "5.2.8",
+  "version": "6.2.0",
   "author": "Sohan Emon <sohanemon@outlook.com>",
   "description": "",
   "type": "module",
@@ -34,9 +34,15 @@
     "README.md"
   ],
   "scripts": {
+    "dev": "tsc --watch",
     "build": "tsc",
-    "build:watch": "tsc --watch",
-    "export": "tsc && npm publish"
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:list": "vitest list",
+    "test:log": "vitest run --reporter verbose",
+    "test:ui": "vitest --ui",
+    "prepublish": "tsc",
+    "publish": "tsc && bun publish"
   },
   "keywords": [
     "utils",
@@ -46,13 +52,14 @@
   "devDependencies": {
     "@types/node": "^24.10.0",
     "@types/react": "^19.2.2",
-    "typescript": "^5.9.3"
+    "@vitest/ui": "^4.0.14",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14"
   },
   "dependencies": {
     "@iconify/react": "^6.0.2",
     "clsx": "^2.1.1",
     "react": "^19.2.0",
     "tailwind-merge": "^3.3.1"
-  },
-  "packageManager": "pnpm@10.11.0+sha512.6540583f41cc5f628eb3d9773ecee802f4f9ef9923cc45b69890fb47991d4b092964694ec3a4f738a420c918a333062c8b925d312f42e4f0c263eb603551f977"
+  }
 }