utills 0.1.2 → 0.1.4

package/README.md

@@ -1,13 +1,13 @@
-# utils
+# utills
 
-![thumbmail](./public/assets/utills-web.jpg)
+![thumbmail](https://raw.githubusercontent.com/safayet35/utills/main/public/assets/utills-web.jpg)
 
 Lightweight, dependency-free utility functions for modern JavaScript and TypeScript projects.
 
-This package is designed to be simple, secure, and developer-friendly.  
+This package is designed to be **simple**, **secure**, and **developer-friendly**.  
 It works in both **Node.js** and **browser environments** and follows modern **ESM standards**.
 
-**Check out** 👉 [Docs](https://utills.vercel.app/)
+👉 **Documentation:** https://utills.vercel.app/
 
 ---
 
@@ -18,30 +18,30 @@ It works in both **Node.js** and **browser environments** and follows modern **E
 -   Zero external dependencies
 -   Tree-shaking friendly
 -   Browser & Node.js support
--   Secure (crypto-based utilities)
+-   Crypto-based secure utilities
+-   Fully unit-tested with **Vitest**
 
 ---
 
 ## 📦 Installation
 
 ```bash
-npm install utils
+npm install utills
 ```
 
 # Usage
 
 ```bash
-
 import {
   randomId,
   timeAgo,
-} from "utils";
+} from "utills";
 
 randomId();
 timeAgo(Date.now() - 60000);
 ```
 
-## Available Utilities
+## Example Utilities
 
 | Method             | Parameters        | Returns  | Description                                                  |
 | ------------------ | ----------------- | -------- | ------------------------------------------------------------ |
@@ -49,9 +49,33 @@ timeAgo(Date.now() - 60000);
 | **generateSecret** | `length?`         | `string` | Generates a cryptographically secure secret token.           |
 | **timeAgo**        | `date`, `locale?` | `string` | Returns human-readable relative time (e.g. "2 minutes ago"). |
 
+## Testing
+
+This project uses Vitest for unit testing.
+
+All utility functions must include tests, even if they generate random values.
+
+Run test
+
+```bash
+npm run test
+```
+
+Testing rules:
+
+-   Each utility must have a corresponding test file
+-   Random-based utilities should be tested using:
+    -   output length
+    -   output type
+    -   allowed character sets
+    -   error cases
+-   Edge cases must be covered
+
 ## Contributing
 
-Contributions are welcome and appreciated.
+Contributions are welcome and appreciated!
+
+Before contributing, please read the guidelines below carefully.
 
 ## How to contribute
 
@@ -76,6 +100,12 @@ git checkout -b feature/new-utility
 src/core/
 ```
 
+Rules
+
+-   One utility per file
+-   Must support both JS & TS
+-   Must handle invalid inputs properly
+
 5: Export it from:
 
 ```bash
@@ -84,13 +114,57 @@ src/core/index.ts
 
 6: Build and test
 
+Add tests using Vitest for your utility.
+
+```bash
+npm run test
+```
+
+Pull requests **without tests will not be accepted**
+
+7: Update Docs (Required)
+
+This project has a docs website.
+
+After adding a utility, you must update the docs data file:
+
+```bash
+docs/src/api/methods.data.js
+```
+
+Add your utility following the existing pattern, including:
+
+-   name
+-   description
+-   parameters
+-   return type
+-   example usage
+
+Example structure:
+
+```bash
+{
+  name: "yourUtility",
+  description: "What this utility does",
+  params: [],
+  returns: "string",
+  example: `import { yourUtility } from "utills"
+
+yourUtility();`
+}
+```
+
+This data is used to render the API documentation UI
+
+8: Build and verify
+
 ```bash
 npm run build
 ```
 
-7: Commit your changes with a clear message
+9: Commit & Open PR
 
-8: Open a Pull Request
+Use clear commit messages and open a Pull Request with a proper description.
 
 ## Contribution Guideline
 
@@ -99,6 +173,8 @@ npm run build
 -   Use native APIs where possible
 -   Handle edge cases properly
 -   Keep code clean and readable
+-   Tests are mandatory
+-   Utilities should be reusable & generic
 
 ## Roadmap
 
@@ -110,3 +186,6 @@ npm run build
 ## License
 
 MIT License © Safayet Rahman
+
+
+

package/dist/core/copyToClipboard.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copies a string to the system clipboard.
+ * Uses the modern Clipboard API where available, with a fallback to `execCommand`
+ * for older browsers or non-secure contexts.
+ *
+ * @param {string} text - The text to copy.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ *
+ * @example
+ * await copyToClipboard("Hello World");
+ *
+ * // Handle result
+ * if (await copyToClipboard("Token")) {
+ * console.log("Copied!");
+ * }
+ */
+export declare function copyToClipboard(text: string): Promise<boolean>;
+//# sourceMappingURL=copyToClipboard.d.ts.map

package/dist/core/copyToClipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copyToClipboard.d.ts","sourceRoot":"","sources":["../../src/core/copyToClipboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAoCpE"}

package/dist/core/copyToClipboard.js

@@ -0,0 +1,50 @@
+/**
+ * Copies a string to the system clipboard.
+ * Uses the modern Clipboard API where available, with a fallback to `execCommand`
+ * for older browsers or non-secure contexts.
+ *
+ * @param {string} text - The text to copy.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ *
+ * @example
+ * await copyToClipboard("Hello World");
+ *
+ * // Handle result
+ * if (await copyToClipboard("Token")) {
+ * console.log("Copied!");
+ * }
+ */
+export async function copyToClipboard(text) {
+    if (typeof window === 'undefined' || !text) {
+        return false;
+    }
+    try {
+        // 1. Try Modern Async API (Secure contexts only)
+        if (navigator?.clipboard?.writeText) {
+            await navigator.clipboard.writeText(text);
+            return true;
+        }
+    }
+    catch (err) {
+        // Continue to fallback if modern API fails
+    }
+    // 2. Fallback for older browsers or non-HTTPS contexts
+    try {
+        const textArea = document.createElement('textarea');
+        textArea.value = text;
+        // Ensure the textarea is not visible but part of the DOM
+        textArea.style.position = 'fixed';
+        textArea.style.left = '-9999px';
+        textArea.style.top = '0';
+        document.body.appendChild(textArea);
+        textArea.focus();
+        textArea.select();
+        const successful = document.execCommand('copy');
+        document.body.removeChild(textArea);
+        return successful;
+    }
+    catch (err) {
+        return false;
+    }
+}
+//# sourceMappingURL=copyToClipboard.js.map

package/dist/core/copyToClipboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copyToClipboard.js","sourceRoot":"","sources":["../../src/core/copyToClipboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY;IAChD,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC;QACH,iDAAiD;QACjD,IAAI,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;YACpC,MAAM,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,2CAA2C;IAC7C,CAAC;IAED,uDAAuD;IACvD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QACpD,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC;QAEtB,yDAAyD;QACzD,QAAQ,CAAC,KAAK,CAAC,QAAQ,GAAG,OAAO,CAAC;QAClC,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,SAAS,CAAC;QAChC,QAAQ,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAEpC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,QAAQ,CAAC,MAAM,EAAE,CAAC;QAElB,MAAM,UAAU,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAChD,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAEpC,OAAO,UAAU,CAAC;IACpB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/core/debounce.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Creates a debounced version of a function that delays its execution.
+ * Useful for optimizing frequent events like search input, resize, or scroll.
+ *
+ * @example
+ * const debouncedFn = debounce((value: string) => {
+ *   console.log(value);
+ * }, 300);
+ *
+ * debouncedFn("hello");
+ */
+export declare function debounce<T extends (...args: any[]) => void>(fn: T, delay: number): {
+    (...args: Parameters<T>): void;
+    cancel: () => void;
+    flush: () => void;
+};
+//# sourceMappingURL=debounce.d.ts.map

package/dist/core/debounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../src/core/debounce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EACzD,EAAE,EAAE,CAAC,EACL,KAAK,EAAE,MAAM,GACZ;IACD,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CA8CA"}

package/dist/core/debounce.js

@@ -0,0 +1,51 @@
+/**
+ * Creates a debounced version of a function that delays its execution.
+ * Useful for optimizing frequent events like search input, resize, or scroll.
+ *
+ * @example
+ * const debouncedFn = debounce((value: string) => {
+ *   console.log(value);
+ * }, 300);
+ *
+ * debouncedFn("hello");
+ */
+export function debounce(fn, delay) {
+    if (typeof fn !== "function") {
+        throw new TypeError("debounce: fn must be a function");
+    }
+    if (typeof delay !== "number" || delay < 0) {
+        throw new TypeError("debounce: delay must be a non-negative number");
+    }
+    let timer = null;
+    let lastArgs = null;
+    const debounced = (...args) => {
+        lastArgs = args;
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(() => {
+            timer = null;
+            if (lastArgs) {
+                fn(...lastArgs);
+                lastArgs = null;
+            }
+        }, delay);
+    };
+    debounced.cancel = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+            lastArgs = null;
+        }
+    };
+    debounced.flush = () => {
+        if (timer && lastArgs) {
+            clearTimeout(timer);
+            fn(...lastArgs);
+            timer = null;
+            lastArgs = null;
+        }
+    };
+    return debounced;
+}
+//# sourceMappingURL=debounce.js.map

package/dist/core/debounce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.js","sourceRoot":"","sources":["../../src/core/debounce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CACtB,EAAK,EACL,KAAa;IAMb,IAAI,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACvE,CAAC;IAED,IAAI,KAAK,GAAyC,IAAI,CAAC;IACvD,IAAI,QAAQ,GAAyB,IAAI,CAAC;IAE1C,MAAM,SAAS,GAAG,CAAC,GAAG,IAAmB,EAAE,EAAE;QAC3C,QAAQ,GAAG,IAAI,CAAC;QAEhB,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,KAAK,GAAG,IAAI,CAAC;YACb,IAAI,QAAQ,EAAE,CAAC;gBACb,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC;gBAChB,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC,EAAE,KAAK,CAAC,CAAC;IACZ,CAAC,CAAC;IAEF,SAAS,CAAC,MAAM,GAAG,GAAG,EAAE;QACtB,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,GAAG,IAAI,CAAC;YACb,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;IACH,CAAC,CAAC;IAEF,SAAS,CAAC,KAAK,GAAG,GAAG,EAAE;QACrB,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;YACtB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC;YAChB,KAAK,GAAG,IAAI,CAAC;YACb,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/core/formatDate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Formats a date into a specific pattern, locale-based style, or relative time.
+ * Supports internationalization (i18n) via locale codes.
+ *
+ * @param {Date | string | number} date - The input date.
+ * @param {string} [format="medium"] - The pattern (e.g., "YYYY-MM-DD"), style ("full", "long", "medium", "short"), or "relative".
+ * @param {string} [locale="en-US"] - The BCP 47 language tag (e.g., "en-US", "bn-BD").
+ * @returns {string} The formatted string.
+ * @throws {TypeError} If the date is invalid.
+ *
+ * @example
+ * // Custom Pattern
+ * formatDate(new Date(), "DD MMMM, YYYY", "bn-BD"); // "২৫ অক্টোবর, ২০২৩"
+ *
+ * // Standard Styles
+ * formatDate(new Date(), "full", "en-US"); // "Wednesday, October 25, 2023"
+ *
+ * // Relative Time
+ * formatDate(Date.now() - 3600000, "relative", "en-US"); // "1 hour ago"
+ * formatDate(Date.now() - 3600000, "relative", "bn-BD"); // "১ ঘণ্টা আগে"
+ */
+export declare function formatDate(date: Date | string | number, format?: string, locale?: string): string;
+//# sourceMappingURL=formatDate.d.ts.map

package/dist/core/formatDate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatDate.d.ts","sourceRoot":"","sources":["../../src/core/formatDate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAC5B,MAAM,GAAE,MAAiB,EACzB,MAAM,GAAE,MAAgB,GACvB,MAAM,CAyER"}

package/dist/core/formatDate.js

@@ -0,0 +1,92 @@
+/**
+ * Formats a date into a specific pattern, locale-based style, or relative time.
+ * Supports internationalization (i18n) via locale codes.
+ *
+ * @param {Date | string | number} date - The input date.
+ * @param {string} [format="medium"] - The pattern (e.g., "YYYY-MM-DD"), style ("full", "long", "medium", "short"), or "relative".
+ * @param {string} [locale="en-US"] - The BCP 47 language tag (e.g., "en-US", "bn-BD").
+ * @returns {string} The formatted string.
+ * @throws {TypeError} If the date is invalid.
+ *
+ * @example
+ * // Custom Pattern
+ * formatDate(new Date(), "DD MMMM, YYYY", "bn-BD"); // "২৫ অক্টোবর, ২০২৩"
+ *
+ * // Standard Styles
+ * formatDate(new Date(), "full", "en-US"); // "Wednesday, October 25, 2023"
+ *
+ * // Relative Time
+ * formatDate(Date.now() - 3600000, "relative", "en-US"); // "1 hour ago"
+ * formatDate(Date.now() - 3600000, "relative", "bn-BD"); // "১ ঘণ্টা আগে"
+ */
+export function formatDate(date, format = "medium", locale = "en-US") {
+    const d = new Date(date);
+    if (isNaN(d.getTime())) {
+        throw new TypeError("Invalid date provided");
+    }
+    // 1. Handle "Relative" Time (e.g., "2 hours ago")
+    if (format === "relative") {
+        const diff = Date.now() - d.getTime();
+        const isFuture = diff < 0;
+        const absDiff = Math.abs(diff);
+        const seconds = Math.floor(absDiff / 1000);
+        const minutes = Math.floor(seconds / 60);
+        const hours = Math.floor(minutes / 60);
+        const days = Math.floor(hours / 24);
+        const months = Math.floor(days / 30);
+        const years = Math.floor(days / 365);
+        // Create localized relative formatter
+        // Note: Intl.RelativeTimeFormat is supported in Node 12+ and all modern browsers
+        const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+        const dir = isFuture ? 1 : -1; // 1 for future ("in..."), -1 for past ("...ago")
+        if (years > 0)
+            return rtf.format(years * dir, "year");
+        if (months > 0)
+            return rtf.format(months * dir, "month");
+        if (days > 0)
+            return rtf.format(days * dir, "day");
+        if (hours > 0)
+            return rtf.format(hours * dir, "hour");
+        if (minutes > 0)
+            return rtf.format(minutes * dir, "minute");
+        return rtf.format(seconds * dir, "second");
+    }
+    // 2. Handle Standard Intl Styles (full, long, medium, short)
+    const styles = ["full", "long", "medium", "short"];
+    if (styles.includes(format)) {
+        return new Intl.DateTimeFormat(locale, {
+            dateStyle: format,
+            // timeStyle can be added optionally, but usually strictly requested for dates
+        }).format(d);
+    }
+    // 3. Handle Custom Token Pattern (e.g., YYYY-MM-DD)
+    // We use Intl for specific names (Months, Days) to support the locale
+    const getPart = (options) => new Intl.DateTimeFormat(locale, options).format(d);
+    const map = {
+        YYYY: getPart({ year: "numeric" }), // 2023 or ২০২৩ (if locale supports numberingSystem)
+        YY: getPart({ year: "2-digit" }),
+        MMMM: getPart({ month: "long" }), // January / জানুয়ারি
+        MMM: getPart({ month: "short" }), // Jan / জানু
+        MM: getPart({ month: "2-digit" }), // 01
+        M: getPart({ month: "numeric" }), // 1
+        dddd: getPart({ weekday: "long" }), // Monday / সোমবার
+        ddd: getPart({ weekday: "short" }), // Mon / সোম
+        DD: getPart({ day: "2-digit" }), // 25
+        D: getPart({ day: "numeric" }), // 25
+        HH: String(d.getHours()).padStart(2, "0"), // Keeping time ISO/numeric for patterns usually
+        H: d.getHours(),
+        hh: String(d.getHours() % 12 || 12).padStart(2, "0"),
+        h: d.getHours() % 12 || 12,
+        mm: String(d.getMinutes()).padStart(2, "0"),
+        ss: String(d.getSeconds()).padStart(2, "0"),
+        a: getPart({ hour: "numeric", hour12: true }).replace(/[^a-zA-Z]/g, ""), // Extract AM/PM locally if possible, or fallback logic
+    };
+    // Custom Regex for replacement
+    const regex = /\[([^\]]+)]|YYYY|YY|MMMM|MMM|MM|M|dddd|ddd|DD|D|HH|H|hh|h|mm|ss|a/g;
+    return format.replace(regex, (match, escapedText) => {
+        if (escapedText)
+            return escapedText;
+        return String(map[match]);
+    });
+}
+//# sourceMappingURL=formatDate.js.map

package/dist/core/formatDate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatDate.js","sourceRoot":"","sources":["../../src/core/formatDate.ts"],"names":[],"mappings":"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"}

package/dist/core/fuzzySearch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Perform an advanced lightweight fuzzy search on an array of objects.
+ * Supports multiple keys, nested keys (dot-notation), case sensitivity,
+ * and partial fuzzy matching.
+ *
+ * Design decision:
+ * - `keys` is OPTIONAL.
+ *   If not provided, all enumerable values of the object are searched.
+ *   This keeps the API flexible while allowing strict control when needed.
+ *
+ * @example
+ * fuzzySearch(users, "john", { keys: ["name", "email"] });
+ *
+ * @example
+ * fuzzySearch(posts, "react", { keys: ["author.name", "title"] });
+ */
+export declare function fuzzySearch<T extends Record<string, any>>(list: T[], query: string, options?: {
+    keys?: string[];
+    caseSensitive?: boolean;
+    threshold?: number;
+}): T[];
+//# sourceMappingURL=fuzzySearch.d.ts.map

package/dist/core/fuzzySearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzzySearch.d.ts","sourceRoot":"","sources":["../../src/core/fuzzySearch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACvD,IAAI,EAAE,CAAC,EAAE,EACT,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IACR,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,CAAC,EAAE,CAsDL"}

package/dist/core/fuzzySearch.js

@@ -0,0 +1,58 @@
+/**
+ * Perform an advanced lightweight fuzzy search on an array of objects.
+ * Supports multiple keys, nested keys (dot-notation), case sensitivity,
+ * and partial fuzzy matching.
+ *
+ * Design decision:
+ * - `keys` is OPTIONAL.
+ *   If not provided, all enumerable values of the object are searched.
+ *   This keeps the API flexible while allowing strict control when needed.
+ *
+ * @example
+ * fuzzySearch(users, "john", { keys: ["name", "email"] });
+ *
+ * @example
+ * fuzzySearch(posts, "react", { keys: ["author.name", "title"] });
+ */
+export function fuzzySearch(list, query, options) {
+    if (!Array.isArray(list)) {
+        throw new TypeError("fuzzySearch: list must be an array");
+    }
+    if (typeof query !== "string") {
+        throw new TypeError("fuzzySearch: query must be a string");
+    }
+    const { keys, caseSensitive = false, threshold = 0.4, } = options || {};
+    if (typeof threshold !== "number" || threshold < 0 || threshold > 1) {
+        throw new TypeError("fuzzySearch: threshold must be between 0 and 1");
+    }
+    if (query.trim() === "")
+        return list;
+    const normalize = (value) => caseSensitive ? value : value.toLowerCase();
+    const normalizedQuery = normalize(query);
+    function getValueByPath(obj, path) {
+        return path
+            .split(".")
+            .reduce((acc, key) => (acc != null ? acc[key] : undefined), obj) ?? "";
+    }
+    function similarity(a, b) {
+        let matches = 0;
+        const len = Math.max(a.length, b.length);
+        for (let i = 0; i < Math.min(a.length, b.length); i++) {
+            if (a[i] === b[i])
+                matches++;
+        }
+        return len === 0 ? 0 : matches / len;
+    }
+    return list.filter((item) => {
+        const values = keys
+            ? keys.map((key) => String(getValueByPath(item, key)))
+            : Object.values(item).map((v) => String(v));
+        return values.some((value) => {
+            const source = normalize(value);
+            if (source.includes(normalizedQuery))
+                return true;
+            return similarity(source, normalizedQuery) >= threshold;
+        });
+    });
+}
+//# sourceMappingURL=fuzzySearch.js.map

package/dist/core/fuzzySearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzzySearch.js","sourceRoot":"","sources":["../../src/core/fuzzySearch.ts"],"names":[],"mappings":"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"}

package/dist/core/generateSecret.d.ts

@@ -7,3 +7,4 @@
  * generateSecret(64)
  */
 export declare function generateSecret(length?: number): string;
+//# sourceMappingURL=generateSecret.d.ts.map

package/dist/core/generateSecret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateSecret.d.ts","sourceRoot":"","sources":["../../src/core/generateSecret.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,MAAW,GAAG,MAAM,CAwB1D"}

package/dist/core/generateSecret.js

@@ -25,3 +25,4 @@ export function generateSecret(length = 32) {
     }
     return secret;
 }
+//# sourceMappingURL=generateSecret.js.map

package/dist/core/generateSecret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateSecret.js","sourceRoot":"","sources":["../../src/core/generateSecret.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE;IAChD,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;IAClE,CAAC;IAED,MAAM,OAAO,GAAG,gEAAgE,CAAA;IAChF,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAA;IAEpC,mCAAmC;IACnC,MAAM,SAAS,GACb,OAAO,MAAM,KAAK,WAAW;QAC3B,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,aAAa;YACb,OAAO,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAA;IAEjC,MAAM,YAAY,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAAA;IAC5C,SAAS,CAAC,eAAe,CAAC,YAAY,CAAC,CAAA;IAEvC,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAA;IACpD,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/core/index.d.ts

@@ -1,3 +1,16 @@
 export { randomId } from "./randomId.js";
 export { generateSecret } from "./generateSecret.js";
 export { timeAgo } from "./timeAgo.js";
+export { timePeriod } from "./timePeriod.js";
+export { readTime } from "./readTime.js";
+export { fuzzySearch } from "./fuzzySearch.js";
+export { debounce } from "./debounce.js";
+export { throttle } from "./throttle.js";
+export { paginate } from "./paginate.js";
+export { slugify } from "./slugify.js";
+export { truncate } from "./truncate.js";
+export { sortBy } from "./sortBy.js";
+export { randomNumber } from "./randomNumber.js";
+export { copyToClipboard } from "./copyToClipboard.js";
+export { formatDate } from "./formatDate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/core/index.js

@@ -1,3 +1,16 @@
 export { randomId } from "./randomId.js";
 export { generateSecret } from "./generateSecret.js";
 export { timeAgo } from "./timeAgo.js";
+export { timePeriod } from "./timePeriod.js";
+export { readTime } from "./readTime.js";
+export { fuzzySearch } from "./fuzzySearch.js";
+export { debounce } from "./debounce.js";
+export { throttle } from "./throttle.js";
+export { paginate } from "./paginate.js";
+export { slugify } from "./slugify.js";
+export { truncate } from "./truncate.js";
+export { sortBy } from "./sortBy.js";
+export { randomNumber } from "./randomNumber.js";
+export { copyToClipboard } from "./copyToClipboard.js";
+export { formatDate } from "./formatDate.js";
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/core/paginate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Create frontend-friendly pagination data from a list.
+ *
+ * @example
+ * paginate(items, { page: 1, pageSize: 10 });
+ */
+export declare function paginate<T>(list: T[], options?: {
+    page?: number;
+    pageSize?: number;
+}): {
+    data: T[];
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+};
+//# sourceMappingURL=paginate.d.ts.map

package/dist/core/paginate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.d.ts","sourceRoot":"","sources":["../../src/core/paginate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,CAAC,EAAE;IACR,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA;IACD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB,CAgCA"}