billy-herrington-utils 2.0.7 → 2.1.0

package/README.md

@@ -1,90 +1,388 @@
 ### _daddy told us not to be ashamed of our utils_
 ![](https://i.imgur.com/wwfRj0R.jpeg)
 
+## Installation
+
+```shell
+npm i billy-herrington-utils
 ```
-<script src="https://unpkg.com/billy-herrington-utils"></script>
-```
-```
+```html
 <script src="https://unpkg.com/billy-herrington-utils/dist/billy-herrington-utils.umd.js"></script>
 <script>
   const { Tick } = window.bhutils;
 </script>
 ```
+
+## 📦 Arrays & Iterables
+
+### chunks
+
+Splits an array into smaller arrays of a specified size.
+
+* **Input**: `arr: T[]`, `size: number`
+* **Output**: `T[][]`
+
+```typescript
+const data = [1, 2, 3, 4, 5]
+const result = chunks(data, 2)
+console.log(result)
+
 ```
-npm i billy-herrington-utils
+
+### range
+
+Generates an array of numbers starting from a specific value.
+
+* **Input**: `size: number`, `start?: number` (default 1), `step?: number` (default 1)
+* **Output**: `number[]`
+
+```typescript
+const numbers = range(5, 0, 10)
+console.log(numbers)
+
 ```
 
-**A comprehensive collection of utility 🛠️ functions to make dungeon life easier.**
+### circularShift
+
+Performs a circular shift on a number within a specific capacity.
 
-**Key features:**
+* **Input**: `n: number` (current index), `c?: number` (capacity, default 6), `s?: number` (shift step, default 1)
+* **Output**: `number`
 
-* **String manipulation:** Easily parse, sanitize, and convert strings.
-* **Time and date:** Work with time and date values effortlessly.
-* **DOM manipulation:** Interact with DOM elements like a pro.
-* **Networking:** Make HTTP requests and handle data with ease.
-* **Miscellaneous:** A variety of other useful functions for common tasks.
+```typescript
+const nextIndex = circularShift(5, 6, 1)
+console.log(nextIndex)
 
-## **Documentation**
+```
 
 ---
 
-### General Utilities
-
-| Function | Short Explanation | Input Parameters | Example Input/Output or Usage |
-|---|---|---|---|
-| `splitWith(s)` | Splits a comma-separated string into an array of lowercase, trimmed words. | `s: string` | `splitWith("Hello, world!, Test_String")` -> `["hello", "world", "test_string"]` |
-| `sanitizeStr(s)` | Cleans up a string by removing newlines/tabs, excess spaces, and converting to lowercase. | `s: string` | `sanitizeStr("  Hello  \nWorld  ")` -> `"hello world"` |
-| `formatTimeToHHMMSS(timeString)` | Formats a time string (e.g., "1h 30min 15sec") into "HH:MM:SS". | `timeString: string` | `formatTimeToHHMMSS("1h 2min")` -> `"01:02:00"` |
-| `timeToSeconds(t)` | Converts a time string (e.g., "1h 30min") or "HH:MM:SS" into total seconds. | `t: string` | `timeToSeconds("1h 2min")` -> `3720` |
-| `parseIntegerOr(n, or)` | Parses a string into an integer, returning a default value if parsing fails. | `n: any`, `or: number` | `parseIntegerOr("100", 0)` -> `100`, `parseIntegerOr("abc", 0)` -> `0` |
-| `parseDataParams(str)` | Parses a string of key-value pairs (`key:value;`) into an object. | `str: string` | `parseDataParams("user:john;id:123")` -> `{user: "john", id: "123"}` |
-| `parseCSSUrl(s)` | Extracts the URL from a CSS `url()` string. | `s: string` | `parseCSSUrl("url(\"https://example.com/img.png\")")` -> `"https://example.com/img.png"` |
-| `circularShift(n, c = 6, s = 1)` | Performs a circular shift on a number within a range. | `n: number`, `c: number`, `s: number` | `circularShift(5, 6, 1)` -> `6` |
-| `range(size, startAt = 1, step = 1)` | Creates an array of numbers in a specified range. | `size: number`, `startAt: number`, `step: number` | `range(3, 2, 2)` -> `[2, 4, 6]` |
-| `chunks(arr, n)` | Splits an array into chunks of a given size. | `arr: Array`, `n: number` | `chunks([1, 2, 3, 4, 5], 2)` -> `[[1, 2], [3, 4], [5]]` |
-| `isMob()` | Checks if the user agent indicates a mobile device. | N/A | `isMob()` -> `true` or `false` |
-| `wait(milliseconds)` | Returns a Promise that resolves after a delay. | `milliseconds: number` | `await wait(1000)` waits for 1 second. |
-| `computeAsyncOneAtTime(iterable)` | Executes an iterable of async functions one at a time. | `iterable: Iterable<Function>` | `await computeAsyncOneAtTime([() => fetch('a'), () => fetch('b')])` |
-| `objectToFormData(object)` | Converts a JavaScript object into a `FormData` object. | `object: object` | `objectToFormData({ key: 'value' })` -> `FormData` object |
+## ⏱️ Async & Timing
+
+### wait
+
+Returns a Promise that resolves after a specified duration.
+
+* **Input**: `milliseconds: number`
+* **Output**: `Promise<void>`
+
+```typescript
+await wait(1000)
+console.log("Done waiting")
+
+```
+
+### Tick
+
+A class for creating repeating intervals with start/stop control and final callbacks.
+
+* **Methods**: `start(callback, callbackFinal?)`, `stop()`
+
+```typescript
+const ticker = new Tick(1000)
+ticker.start(
+  () => console.log("Tick"),
+  () => console.log("Stopped")
+)
+await wait(3000)
+ticker.stop()
+
+```
 
 ---
 
-### DOM Manipulation
-
-| Function | Short Explanation | Input Parameters | Example Input/Output or Usage |
-|---|---|---|---|
-| `parseDom(html)` | Parses an HTML string into a DOM element. | `html: string` | `parseDom("<div>Hello</div>")` -> `HTMLDivElement` |
-| `copyAttributes(target, source)` | Copies all attributes from one element to another. | `target: HTMLElement`, `source: HTMLElement` | `copyAttributes(div1, div2)` |
-| `replaceElementTag(e, tagName)` | Replaces an element's tag while preserving its content and attributes. | `e: HTMLElement`, `tagName: string` | `replaceElementTag(document.querySelector('p'), 'div')` |
-| `getAllUniqueParents(elements)` | Returns an array of unique parent elements. | `elements: Array<HTMLElement>` | `getAllUniqueParents([el1, el2])` |
-| `findNextSibling(el)` | Finds the next sibling, or recursively checks parent elements. | `el: HTMLElement` | `findNextSibling(document.querySelector('li'))` |
-| `waitForElementToAppear(parent, selector, callback)` | Waits for an element to exist in the DOM and then runs a callback. | `parent: HTMLElement`, `selector: string`, `callback: Function` | `waitForElementToAppear(document.body, '.my-class', (el) => console.log(el))` |
-| `watchElementChildrenCount(element, callback)` | Observes an element for changes in its number of children. | `element: HTMLElement`, `callback: Function` | `watchElementChildrenCount(list, (obs, count) => console.log(count))` |
-| `watchDomChangesWithThrottle(element, callback, throttle, times, options)` | Watches for DOM changes with a throttle to prevent excessive callbacks. | `element: HTMLElement`, `callback: Function`, `throttle: number`, `times: number`, `options: object` | `watchDomChangesWithThrottle(body, () => ..., 500)` |
-| `downloader(options)` | Creates a button to download a video from the page. | `options: object` | `downloader({ button: '<button>Download</button>', append: 'body' })` |
-| `exterminateVideo(video)` | Removes a video element and stops it from loading. | `video: HTMLVideoElement` | `exterminateVideo(document.querySelector('video'))` |
-| `listenEvents(dom, events, callback)` | Adds multiple event listeners to a DOM element. | `dom: HTMLElement`, `events: Array<string>`, `callback: Function` | `listenEvents(btn, ['click', 'mouseover'], handler)` |
+## 📝 String & Formatting
+
+### splitWith
+
+Splits a string by a delimiter, trims whitespace, and filters out empty strings.
+
+* **Input**: `s: string`, `c?: string` (delimiter, default ",")
+* **Output**: `string[]`
+
+```typescript
+const tags = splitWith(" apple, banana , , orange ")
+console.log(tags)
+
+```
+
+### sanitizeStr
+
+Removes newlines, tabs, and excessive whitespace from a string.
+
+* **Input**: `s: string`
+* **Output**: `string`
+
+```typescript
+const raw = "  Hello \n\t  World  "
+const clean = sanitizeStr(raw)
+console.log(clean)
+
+```
+
+### timeToSeconds
+
+Converts a time string (e.g., "1h 30min" or "01:30:00") into total seconds.
+
+* **Input**: `timeStr: string`
+* **Output**: `number`
+
+```typescript
+const totalSeconds = timeToSeconds("1h 2min 30sec")
+
+```
+
+### formatTimeToHHMMSS
+
+Formats a descriptive time string into a standard HH:MM:SS format.
+
+* **Input**: `timeStr: string`
+* **Output**: `string`
+
+```typescript
+const stamp = formatTimeToHHMMSS("1h 5min")
+console.log(stamp)
+
+```
 
 ---
 
-### Network Utilities
+## 🕸️ Network
+
+### fetchWith
+
+A wrapper around the native `fetch` API that supports a mobile User-Agent spoofing and automatic response parsing.
+
+* **Input**: `input: string`, `options: { type?: 'json' | 'html' | 'text', mobile?: boolean, init?: RequestInit }`
+* **Output**: `Promise<any>`
+
+```typescript
+const data = await fetchWith("https://api.example.com/data", {
+  type: "json",
+  mobile: true
+})
+
+```
 
-| Function | Short Explanation | Input Parameters | Example Input/Output or Usage |
-|---|---|---|---|
-| `fetchWith(url, options)` | A flexible wrapper for the `fetch` API with options for HTML parsing and mobile user agents. | `url: string`, `options: object` | `fetchWith('https://example.com', { html: true })` |
-| `fetchHtml(url)` | Fetches a URL and parses the response as HTML. | `url: string` | `fetchHtml('https://example.com/page.html')` |
-| `fetchText(url)` | Fetches a URL and returns the response as plain text. | `url: string` | `fetchText('https://example.com/data.txt')` |
+### fetchHtml / fetchJson / fetchText
+
+Shorthand functions for `fetchWith` with specific return types.
+
+* **Input**: `input: string`
+* **Output**: `Promise<HTMLElement | object | string>`
+
+```typescript
+const doc = await fetchHtml("https://example.com")
+const json = await fetchJson("https://api.example.com")
+
+```
 
 ---
 
-### Classes
-
-| Class | Short Explanation | Methods | Usage |
-|---|---|---|---|
-| `Observer` | A wrapper around the native `IntersectionObserver`. | `observe(target)`, `throttle(target, time)`, `static observeWhile(...)` | `const obs = new Observer(cb); obs.observe(target);` |
-| `LazyImgLoader` | Handles lazy-loading images using `IntersectionObserver`. | `lazify(_target, img, imgSrc)`, `delazify(target)` | `const loader = new LazyImgLoader(shouldLoad); loader.lazify(div, img, 'src');` |
-| `Tick` | A utility for creating timed intervals. | `start(callback, finalCallback)`, `stop()` | `const ticker = new Tick(1000); ticker.start(() => console.log('tick'), () => console.log('done'));` |
-| `AsyncPool` | Manages a pool of asynchronous tasks with a concurrency limit. | `push(task)`, `run()`, `static doNAsyncAtOnce(...)` | `const pool = new AsyncPool(2); pool.push(task1); pool.push(task2); pool.run();` |
-| `DataManager` | A class for managing, filtering, and sorting data from a webpage. | `applyFilters(filters, offset)`, `filterAll(offset)`, `parseData(html, container, ...)` | `const dm = new DataManager(rules, state); dm.parseData(html);` |
-| `InfiniteScroller` | Implements infinite scrolling by loading new content when the user reaches the end of the page. | `onScroll(callback)`, `_onScroll()` | `const iscroll = new InfiniteScroller({ ...rules });` |
-| `RulesHelper` | A helper class for defining website-specific rules. | `router(store, cb)`, `_IS_VIDEO_PAGE()`, `_IS_SEARCH_PAGE()` | `const rules = new RulesHelper(options); rules.router(store, cb);` |
+## 🌲 DOM Manipulation
+
+### parseHtml
+
+Parses a raw HTML string and returns a DOM element (or body if multiple children exist).
+
+* **Input**: `html: string`
+* **Output**: `HTMLElement`
+
+```typescript
+const element = parseHtml("<div><span>Hello</span></div>")
+document.body.append(element)
+
+```
+
+### querySelectorLast
+
+Selects the last element matching a selector within a root.
+
+* **Input**: `root?: ParentNode`, `selector: string`
+* **Output**: `Element | undefined`
+
+```typescript
+const lastItem = querySelectorLast(document, ".list-item")
+
+```
+
+### querySelectorText
+
+Safely extracts and sanitizes the inner text of an element matching the selector.
+
+* **Input**: `e: Element`, `selector: string`
+* **Output**: `string`
+
+```typescript
+const title = querySelectorText(document.body, "h1.main-title")
+
+```
+
+### replaceElementTag
+
+Replaces an existing DOM element with a new element of a different tag name, preserving attributes and content.
+
+* **Input**: `e: Element`, `tagName: string`
+* **Output**: `Element` (the new element)
+
+```typescript
+const oldDiv = document.querySelector("#container")
+const newSection = replaceElementTag(oldDiv, "section")
+
+```
+
+### instantiateTemplate
+
+Creates a DOM element from a selector, updating specific attributes and text content during cloning.
+
+* **Input**: `sourceSelector: string`, `attributeUpdates: object`, `contentUpdates: object`
+* **Output**: `string` (innerHTML of the wrapper)
+
+```typescript
+const html = instantiateTemplate(
+  "#card-template",
+  { "data-id": "123" },
+  { ".card-title": "New Item" }
+)
+
+```
+
+---
+
+## 👁️ DOM Observers
+
+### waitForElementToAppear
+
+Watches the DOM until an element matching the selector appears, then executes a callback.
+
+* **Input**: `parent: Node`, `selector: string`, `callback: (el: Element) => void`
+* **Output**: `MutationObserver`
+
+```typescript
+waitForElementToAppear(document.body, ".modal-popup", (modal) => {
+  console.log("Modal is ready", modal)
+})
+
+```
+
+### waitForElementToDisappear
+
+Watches an element and triggers a callback when it is removed from the DOM.
+
+* **Input**: `observable: Element`, `callback: () => void`
+* **Output**: `MutationObserver`
+
+```typescript
+const loadingSpinner = document.querySelector("#spinner")
+waitForElementToDisappear(loadingSpinner, () => {
+  console.log("Loading finished")
+})
+
+```
+
+### watchDomChangesWithThrottle
+
+Observes DOM changes and executes a callback with a throttle (rate limit).
+
+* **Input**: `element: Node`, `callback: () => void`, `throttle?: number`
+* **Output**: `MutationObserver`
+
+```typescript
+watchDomChangesWithThrottle(document.body, () => {
+  console.log("DOM changed")
+}, 500)
+
+```
+
+---
+
+## 🧬 Objects & Logic
+
+### memoize
+
+Creates a function that caches the result of calls with identical arguments.
+
+* **Input**: `fn: Function`
+* **Output**: `Function`
+
+```typescript
+const heavyCalc = (x) => x * x
+const cachedCalc = memoize(heavyCalc)
+cachedCalc(5)
+cachedCalc(5)
+
+```
+
+### propsDifference
+
+Compares two objects and returns the property names that are unique to each.
+
+* **Input**: `obj1: object`, `obj2: object`
+* **Output**: `{ d1: string[], d2: string[] }`
+
+```typescript
+const diff = propsDifference({ a: 1, b: 2 }, { b: 3, c: 4 })
+console.log(diff)
+
+```
+
+### objectToFormData
+
+Converts a plain JavaScript object into a `FormData` object.
+
+* **Input**: `obj: Record<string, any>`
+* **Output**: `FormData`
+
+```typescript
+const form = objectToFormData({ username: "admin", file: blob })
+
+```
+
+---
+
+## 🛠️ Specialized Classes
+
+### RegexFilter
+
+A utility to compile and test strings against complex filter queries (supports OR logic, full-word search, and regex prefixes).
+
+* **Usage**: Create with a query string, then use `hasEvery` or `hasNone`.
+
+```typescript
+const filter = new RegexFilter("dog, cat, f:bird")
+const isMatch = filter.hasEvery("I have a dog and a bird")
+
+```
+
+### OnHover
+
+Handles complex hover interactions, including tracking when the pointer leaves a specific subject.
+
+* **Usage**: Instantiate with a container and a subject selector.
+
+```typescript
+OnHover.create(
+  document.body,
+  (el) => el.classList.contains("tooltip-target"),
+  (target) => {
+    console.log("Hovering", target)
+    return {
+      onOverCallback: () => console.log("Finally block")
+    }
+  }
+)
+
+```
+
+### LazyImgLoader
+
+Manages lazy loading of images by observing intersection and swapping data attributes for source URLs.
+
+* **Usage**: Use `lazify` to setup an image and `delazify` to load it immediately.
+
+```typescript
+const loader = new LazyImgLoader((target) => true)
+const img = document.querySelector("img")
+loader.lazify(img, "https://example.com/image.jpg")
+
+```