@sohanemon/utils 4.1.2 → 4.1.4

package/README.md

@@ -0,0 +1,272 @@
+# sohanemon/utils
+
+![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)
+
+## 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.
+
+## Features
+
+- **Object Utilities**: Functions to manipulate and access nested object properties.
+- **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.
+
+## Installation
+
+You can install `sohanemon/utils` using npm or yarn:
+
+```bash
+npm install @sohanemon/utils
+```
+
+or
+
+```bash
+yarn add @sohanemon/utils
+```
+
+## Usage
+
+### Importing Utilities
+
+You can import individual utilities or hooks as needed:
+
+```javascript
+import { cn, getObjectValue, setClientSideCookie } from '@sohanemon/utils';
+```
+
+### Examples
+
+#### Class Name Merging
+
+```javascript
+import { cn } from '@sohanemon/utils';
+
+const className = cn('bg-blue-500', 'text-white', 'p-4', 'rounded-lg');
+```
+
+#### Object Utilities
+
+```javascript
+import { getObjectValue } from '@sohanemon/utils';
+
+const obj = { a: { b: { c: 1 } } };
+const value = getObjectValue(obj, 'a.b.c'); // 1
+```
+
+#### Cookie Management
+
+```javascript
+import { setClientSideCookie, getClientSideCookie } from '@sohanemon/utils';
+
+setClientSideCookie('username', 'sohanemon', 7);
+const { value } = getClientSideCookie('username'); // 'sohanemon'
+```
+
+#### Responsive Media Queries
+
+```javascript
+import { useMediaQuery } from '@sohanemon/utils';
+
+const isMobile = useMediaQuery('sm');
+```
+
+#### Debounce and Throttle
+
+```javascript
+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();
+
+return (
+  <div>
+    <button onClick={() => copy('Hello, World!')}>Copy</button>
+    {isCopied && <span>Copied!</span>}
+  </div>
+);
+```
+
+#### Local Storage Management
+
+```javascript
+import { useLocalStorage } from '@sohanemon/utils/hooks';
+
+const [value, setValue] = useLocalStorage('myKey', 'initialValue');
+
+return (
+  <div>
+    <input
+      type="text"
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  </div>
+);
+```
+
+#### URL Parameter Management
+
+```javascript
+import { useUrlParams } from '@sohanemon/utils/hooks';
+
+const [param, setParam] = useUrlParams('myParam', 'defaultValue');
+
+return (
+  <div>
+    <input
+      type="text"
+      value={param}
+      onChange={(e) => setParam(e.target.value)}
+    />
+  </div>
+);
+```
+
+#### DOM Calculation
+
+```javascript
+import { useDomCalculation } from '@sohanemon/utils/hooks';
+
+const { height, width } = useDomCalculation({
+  blockIds: ['header', 'footer'],
+  margin: 20,
+  substract: true,
+});
+
+return (
+  <div style={{ height, width }}>
+    Content
+  </div>
+);
+```
+
+## API Documentation
+
+### Class Name Merging
+
+```typescript
+cn(...inputs: ClassValue[]): string
+```
+
+### Object Utilities
+
+```typescript
+getObjectValue<T, K extends Array<string | number>, D>(
+  obj: T,
+  path: K,
+  defaultValue: D
+): Exclude<GetValue<T, K>, undefined> | D;
+
+getObjectValue<T, K extends Array<string | number>>(
+  obj: T,
+  path: K
+): GetValue<T, K> | undefined;
+
+getObjectValue<T, S extends string, D>(
+  obj: T,
+  path: S,
+  defaultValue: D
+): Exclude<GetValue<T, SplitPath<S>>, undefined> | D;
+
+getObjectValue<T, S extends string>(
+  obj: T,
+  path: S
+): GetValue<T, SplitPath<S>> | undefined;
+```
+
+### 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 }
+```
+
+### Responsive Media Queries
+
+```typescript
+useMediaQuery(tailwindBreakpoint: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | `(${string})`): boolean
+```
+
+### Debounce and Throttle
+
+```typescript
+debounce<F extends (...args: any[]) => any>(
+  function_: F,
+  wait?: number,
+  options?: { immediate?: boolean }
+): DebouncedFunction<F>
+
+throttle<F extends (...args: any[]) => any>(
+  function_: F,
+  wait?: number,
+  options?: { leading?: boolean; trailing?: boolean }
+): ThrottledFunction<F>
+```
+
+### Copy to Clipboard
+
+```typescript
+useCopyToClipboard({ timeout?: number }): { isCopied: boolean; copy: (value: string) => void }
+```
+
+### Local Storage Management
+
+```typescript
+useLocalStorage<T extends Record<string, any>>(key: string, defaultValue: T): LocalStorageValue<T>
+```
+
+### URL Parameter Management
+
+```typescript
+useUrlParams<T extends string | number | boolean>(key: string, defaultValue: T): [T, (value: T) => void]
+```
+
+### DOM Calculation
+
+```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 }
+```
+
+## Contributing
+
+Contributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines on how to contribute to the project.
+
+## License
+
+This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+- **Sohan Emon**: [sohanemon@outlook.com](mailto:sohanemon@outlook.com)
+- **GitHub**: [sohanemon](https://github.com/sohanemon)

package/dist/functions/index.d.ts

@@ -7,6 +7,7 @@
 import { type ClassValue } from 'clsx';
 import type * as React from 'react';
 export * from './cookie';
+export * from './object';
 export declare function cn(...inputs: ClassValue[]): string;
 /**
  * @deprecated Use isLinkActive instead.
@@ -60,6 +61,16 @@ export declare const copyToClipboard: (value: string, onSuccess?: () => void) =>
  * @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.
  *

package/dist/functions/index.js

@@ -8,6 +8,7 @@ import { clsx } from 'clsx';
 import { extendTailwindMerge } from 'tailwind-merge';
 import { withFluid } from '@fluid-tailwind/tailwind-merge';
 export * from './cookie';
+export * from './object';
 export function cn(...inputs) {
     const twMerge = extendTailwindMerge(withFluid);
     return twMerge(clsx(inputs));
@@ -109,6 +110,38 @@ export function convertToNormalCase(inputString) {
     const capitalizedWords = words.map((word) => word.charAt(0).toUpperCase() + word.slice(1));
     return capitalizedWords.join(' ');
 }
+const from = 'àáãäâèéëêìíïîòóöôùúüûñç·/_,:;';
+const to = 'aaaaaeeeeiiiioooouuuunc------';
+/**
+ * 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 const convertToSlug = (str) => {
+    if (typeof str !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    // Trim the string and convert it to lowercase.
+    let slug = str.trim().toLowerCase();
+    // Build a mapping of accented characters to their non-accented equivalents.
+    const charMap = {};
+    for (let i = 0; i < from.length; i++) {
+        charMap[from.charAt(i)] = to.charAt(i);
+    }
+    // Replace all accented characters using the mapping.
+    slug = slug.replace(new RegExp(`[${from}]`, 'g'), (match) => charMap[match] || match);
+    return (slug
+        .replace(/[^a-z0-9 -]/g, '') // Remove invalid characters
+        .replace(/\s+/g, '-') // Replace spaces with hyphens
+        .replace(/-+/g, '-') // Collapse consecutive hyphens
+        .replace(/^-+/, '') // Remove leading hyphens
+        .replace(/-+$/, '') || // Remove trailing hyphens
+        '');
+};
 /**
  * Checks if the code is running in a server-side environment.
  *

package/dist/functions/object.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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;
+export {};

package/dist/functions/object.js

@@ -0,0 +1,39 @@
+/**
+ * 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sohanemon/utils",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "author": "Sohan Emon <sohanemon@outlook.com>",
   "description": "",
   "type": "module",