umaki 0.7.6 → 0.8.1

package/README.md

@@ -76,6 +76,9 @@ console.log(breakpoint); // e.g. 768 (default) or custom value if set
 
 ## List of Utilities
 
+- [Callback](#callback)
+  - [tap](#tap)
+  - [tapAsync](#tapasync)
 - [Control](#control)
   - [bgScrollStop](#bgscrollstop)
   - [pd](#pd)
@@ -136,6 +139,69 @@ console.log(breakpoint); // e.g. 768 (default) or custom value if set
   - [waitForAllMediaLoaded](#waitforallmedialoaded)
 - [Security](#security)
   - [sanitizeHtml](#sanitizehtml)
+- [Advanced Usage](#advanced-usage)
+  - [Using tap / tapAsync with umaki functions](#using-tap--tapasync-with-umaki-functions)
+
+## Callback
+
+### tap
+
+A function that executes a callback with the given value and returns the original value unchanged. Useful for performing side effects (logging, caching, analytics, etc.) without modifying the value.
+
+**Note:** This function does not accept Promise values. For async operations, use `tapAsync` instead.
+
+```ts
+import { tap, removeAllHtmlTags } from "umaki";
+
+const input = "<p>Hello <strong>World</strong>!</p>";
+const output = tap(removeAllHtmlTags(input), (result) => {
+  console.log("Sanitized:", result);
+});
+// Logs: 'Sanitized: Hello World!'
+// output = 'Hello World!'
+
+// Caching example
+const data = tap(processData(raw), (result) => {
+  cache.set("processed", result);
+});
+
+// Works with higher-order functions
+const debouncedFn = tap(debounce(handler, 100), () => {
+  console.log("Debounced function created");
+});
+```
+
+[View file →](src/libs/callback/tap.ts)
+
+### tapAsync (Promise)
+
+A function that awaits a Promise, executes a callback with the resolved value, and returns the original value. Useful for performing side effects on async values without modifying them.
+
+```ts
+import { tapAsync } from "umaki";
+
+// Logging async results
+const data = await tapAsync(fetchData(), (result) => {
+  console.log("Fetched:", result);
+});
+
+// Caching async results
+const getData = () =>
+  tapAsync(fetchFromServer(), (data) => cache.set("data", data));
+
+// Parallel execution with individual completion tracking
+await Promise.all([
+  tapAsync(fetchUserData(), (user) => console.log("user loaded")),
+  tapAsync(fetchProductData(), (products) => console.log("products loaded")),
+  tapAsync(fetchOrderData(), (orders) => console.log("orders loaded")),
+]);
+
+// Event emission on async completion
+const loadUser = () =>
+  tapAsync(fetchUser(), (user) => eventEmitter.emit("userLoaded", user));
+```
+
+[View file →](src/libs/callback/tap-async.ts)
 
 ## Control
 
@@ -150,7 +216,7 @@ bgScrollStop(); // scroll stop
 bgScrollStop(false); // scroll start
 ```
 
-[View file →](src/libs/control/bgScrollStop.ts)
+[View file →](src/libs/control/bg-scroll-stop.ts)
 
 ### pd
 
@@ -182,7 +248,7 @@ import { scrollToHash } from "umaki";
 })();
 ```
 
-[View file →](src/libs/control/scrollToHash.ts)
+[View file →](src/libs/control/scroll-to-hash.ts)
 
 ### videoPlayControl
 
@@ -199,7 +265,7 @@ videoPlayControl(videoElement, false); // pause
 videoPlayControl(videoElement, true, 10); // play and set currentTime to 10
 ```
 
-[View file →](src/libs/control/videoPlayControl.ts)
+[View file →](src/libs/control/video-play-control.ts)
 
 ## Convert
 
@@ -235,7 +301,7 @@ console.log(formattedDateWithDifferentTz); // '2025-04-24 20:00:00'
 
 Note: This function focuses on timezone handling rather than locale-specific formatting. When a timezone is specified, the date will be converted to that timezone before formatting.
 
-[View file →](src/libs/convert/changeDateStringToSpecificFormat.ts)
+[View file →](src/libs/convert/change-date-string-to-specific-format.ts)
 
 ### jsonStringToJsonObject
 
@@ -249,7 +315,7 @@ const jsonObject = jsonStringToJsonObject(jsonString);
 console.log(jsonObject); // { name: 'John', age: 30 }
 ```
 
-[View file →](src/libs/convert/jsonStringToJsonObject.ts)
+[View file →](src/libs/convert/json-string-to-json-object.ts)
 
 ## EventControl
 
@@ -298,7 +364,7 @@ const aspectRatio = getAspectRatio(1920, 1080);
 console.log(aspectRatio); // { w: 16, h: 9 }
 ```
 
-[View file →](src/libs/get/getAspectRatio.ts)
+[View file →](src/libs/get/get-aspect-ratio.ts)
 
 ### getClassNames
 
@@ -313,7 +379,7 @@ const classNames = getClassNames(element);
 console.log(classNames); // ['class1', 'class2', 'class3']
 ```
 
-[View file →](src/libs/get/getClassNames.ts)
+[View file →](src/libs/get/get-class-names.ts)
 
 ### getDocumentHeight
 
@@ -326,7 +392,7 @@ const height = getDocumentHeight();
 console.log(height);
 ```
 
-[View file →](src/libs/get/getDocumentHeight.ts)
+[View file →](src/libs/get/get-document-height.ts)
 
 ### getEventPaths
 
@@ -341,7 +407,7 @@ document.addEventListener("click", (event) => {
 });
 ```
 
-[View file →](src/libs/get/getEventPaths.ts)
+[View file →](src/libs/get/get-event-paths.ts)
 
 ### getGcd
 
@@ -354,7 +420,7 @@ const gcd = getGcd(48, 18);
 console.log(gcd); // 6
 ```
 
-[View file →](src/libs/get/getGcd.ts)
+[View file →](src/libs/get/get-gcd.ts)
 
 ### getGravatarUrl
 
@@ -375,7 +441,7 @@ const normalizedAvatar = getGravatarUrl(' USER@EXAMPLE.COM ', 80);
 // Same result as above due to normalization
 ```
 
-[View file →](src/libs/get/getGravatarUrl.ts)
+[View file →](src/libs/get/get-gravatar-url.ts)
 
 ### getOrientation
 
@@ -388,7 +454,7 @@ const orientation = getOrientation();
 console.log(orientation); // 'landscape' or 'portrait'
 ```
 
-[View file →](src/libs/get/getOrientation.ts)
+[View file →](src/libs/get/get-orientation.ts)
 
 ### getParentList
 
@@ -402,7 +468,7 @@ const parentList = getParentList(element);
 console.log(parentList);
 ```
 
-[View file →](src/libs/get/getParentList.ts)
+[View file →](src/libs/get/get-parent-list.ts)
 
 ### getQueryParams
 
@@ -429,7 +495,7 @@ const customParamWithOptions = getQueryParams("id", {
 });
 ```
 
-[View file →](src/libs/get/getQueryParams.ts)
+[View file →](src/libs/get/get-query-params.ts)
 
 ### getRem
 
@@ -442,7 +508,7 @@ const remValue = getRem(16);
 console.log(remValue); // '1rem'
 ```
 
-[View file →](src/libs/get/getRem.ts)
+[View file →](src/libs/get/get-rem.ts)
 
 ### getScrollbarWidth
 
@@ -455,7 +521,7 @@ const scrollbarWidth = getScrollbarWidth();
 console.log(scrollbarWidth); // 15
 ```
 
-[View file →](src/libs/get/getScrollbarWidth.ts)
+[View file →](src/libs/get/get-scrollbar-width.ts)
 
 ### getSessionStorage
 
@@ -468,7 +534,7 @@ const value = getSessionStorage("testKey");
 console.log(value); // 'testValue'
 ```
 
-[View file →](src/libs/get/getSessionStorage.ts)
+[View file →](src/libs/get/get-session-storage.ts)
 
 ### getStringLength
 
@@ -481,7 +547,7 @@ const length = getStringLength("こんにちは");
 console.log(length); // 5
 ```
 
-[View file →](src/libs/get/getStringLength.ts)
+[View file →](src/libs/get/get-string-length.ts)
 
 ### getStylePropertyValue
 
@@ -494,7 +560,7 @@ const value = getStylePropertyValue("--custom-property");
 console.log(value);
 ```
 
-[View file →](src/libs/get/getStylePropertyValue.ts)
+[View file →](src/libs/get/get-style-property-value.ts)
 
 ### getStylePropertyValueToNumber
 
@@ -507,7 +573,7 @@ const value = getStylePropertyValueToNumber("--custom-property");
 console.log(value);
 ```
 
-[View file →](src/libs/get/getStylePropertyValueToNumber.ts)
+[View file →](src/libs/get/get-style-property-value-to-number.ts)
 
 ### getUaData
 
@@ -528,7 +594,7 @@ console.log(uaData);
 // }
 ```
 
-[View file →](src/libs/get/getUaData.ts)
+[View file →](src/libs/get/get-ua-data.ts)
 
 ## Is
 
@@ -550,7 +616,7 @@ const customCurrentDate = "2023-11-15";
 const resultWithCustomDate = isAfterDateTime(targetDate, dayjs(customCurrentDate));
 ```
 
-[View file →](src/libs/is/isAfterDateTime.ts)
+[View file →](src/libs/is/is-after-date-time.ts)
 
 ### isBetweenDateTime
 
@@ -565,7 +631,7 @@ const result = isBetweenDateTime(dateA, dateB);
 console.log(result); // true or false
 ```
 
-[View file →](src/libs/is/isBetweenDateTime.ts)
+[View file →](src/libs/is/is-between-date-time.ts)
 
 ### isExistAllElements
 
@@ -582,7 +648,7 @@ const result = isExistAllElements(elements);
 console.log(result); // true or false
 ```
 
-[View file →](src/libs/is/isExistAllElements.ts)
+[View file →](src/libs/is/is-exist-all-elements.ts)
 
 ### isIpad
 
@@ -595,7 +661,7 @@ const result = isIpad();
 console.log(result); // true or false
 ```
 
-[View file →](src/libs/is/isIpad.ts)
+[View file →](src/libs/is/is-ipad.ts)
 
 ### isKeyExists
 
@@ -609,7 +675,7 @@ const result = isKeyExists(obj, "a");
 console.log(result); // true or false
 ```
 
-[View file →](src/libs/is/isKeyExists.ts)
+[View file →](src/libs/is/is-key-exists.ts)
 
 ### isSafari
 
@@ -622,7 +688,7 @@ const result = isSafari();
 console.log(result); // true or false
 ```
 
-[View file →](src/libs/is/isSafari.ts)
+[View file →](src/libs/is/is-safari.ts)
 
 ### isScrollable
 
@@ -638,7 +704,7 @@ const result = isScrollable(element);
 console.log(result); // true or false
 ```
 
-[View file →](src/libs/is/isScrollable.ts)
+[View file →](src/libs/is/is-scrollable.ts)
 
 ### isTouchSupport
 
@@ -651,7 +717,7 @@ const result = isTouchSupport();
 console.log(result); // true or false
 ```
 
-[View file →](src/libs/is/isTouchSupport.ts)
+[View file →](src/libs/is/is-touch-support.ts)
 
 ### checkDeviceSize
 
@@ -670,7 +736,7 @@ const newDeviceSize = checkDeviceSize();
 console.log(newDeviceSize); // 'md' if window.innerWidth > 1024, otherwise 'sm'
 ```
 
-[View file →](src/libs/is/checkDeviceSize.ts)
+[View file →](src/libs/is/check-device-size.ts)
 
 ## Remove
 
@@ -686,7 +752,7 @@ const output = removeAllHtmlTags(input);
 console.log(output); // 'Hello World!'
 ```
 
-[View file →](src/libs/remove/removeAllHtmlTags.ts)
+[View file →](src/libs/remove/remove-all-html-tags.ts)
 
 ### removeAttribute
 
@@ -701,7 +767,7 @@ removeAttribute(element, "data-test");
 console.log(element.hasAttribute("data-test")); // false
 ```
 
-[View file →](src/libs/remove/removeAttribute.ts)
+[View file →](src/libs/remove/remove-attribute.ts)
 
 ### removeSessionStorage
 
@@ -715,7 +781,7 @@ removeSessionStorage(key);
 console.log(sessionStorage.getItem(key)); // null
 ```
 
-[View file →](src/libs/remove/removeSessionStorage.ts)
+[View file →](src/libs/remove/remove-session-storage.ts)
 
 ### removeStylePropertyValue
 
@@ -729,7 +795,7 @@ removeStylePropertyValue(key);
 console.log(getComputedStyle(document.documentElement).getPropertyValue(key)); // ''
 ```
 
-[View file →](src/libs/remove/removeStylePropertyValue.ts)
+[View file →](src/libs/remove/remove-style-property-value.ts)
 
 ## Set
 
@@ -743,7 +809,7 @@ import { set100vh } from "umaki";
 set100vh();
 ```
 
-[View file →](src/libs/set/set100vh.ts)
+[View file →](src/libs/set/set-100vh.ts)
 
 ### set100vw
 
@@ -755,7 +821,7 @@ import { set100vw } from "umaki";
 set100vw();
 ```
 
-[View file →](src/libs/set/set100vw.ts)
+[View file →](src/libs/set/set-100vw.ts)
 
 ### setAttribute
 
@@ -769,7 +835,7 @@ setAttribute(element, "data-test", "value");
 console.log(element.getAttribute("data-test")); // 'value'
 ```
 
-[View file →](src/libs/set/setAttribute.ts)
+[View file →](src/libs/set/set-attribute.ts)
 
 ### setScrollPositionToCenter
 
@@ -783,7 +849,7 @@ const targetElement = document.getElementById("target");
 setScrollPositionToCenter(rootElement, targetElement);
 ```
 
-[View file →](src/libs/set/setScrollPositionToCenter.ts)
+[View file →](src/libs/set/set-scroll-position-to-center.ts)
 
 ### setSessionStorage
 
@@ -798,7 +864,7 @@ setSessionStorage(key, value);
 console.log(sessionStorage.getItem(key)); // 'testValue'
 ```
 
-[View file →](src/libs/set/setSessionStorage.ts)
+[View file →](src/libs/set/set-session-storage.ts)
 
 ### setStylePropertyValue
 
@@ -813,7 +879,7 @@ setStylePropertyValue(key, value);
 console.log(getComputedStyle(document.documentElement).getPropertyValue(key)); // 'blue'
 ```
 
-[View file →](src/libs/set/setStylePropertyValue.ts)
+[View file →](src/libs/set/set-style-property-value.ts)
 
 ## To
 
@@ -829,7 +895,7 @@ console.log(toBoolean("false")); // false
 console.log(toBoolean("random")); // false
 ```
 
-[View file →](src/libs/to/toBoolean.ts)
+[View file →](src/libs/to/to-boolean.ts)
 
 ### toPositiveNumber
 
@@ -845,7 +911,7 @@ console.log(toPositiveNumber(-3.14)); // 3.14
 console.log(toPositiveNumber(3.14)); // 3.14
 ```
 
-[View file →](src/libs/to/toPositiveNumber.ts)
+[View file →](src/libs/to/to-positive-number.ts)
 
 ## Transform
 
@@ -862,7 +928,7 @@ wrapTextWithSpans(element);
 console.log(element.innerHTML); // '<span>h</span><span>e</span><span>l</span><span>l</span><span>o</span>'
 ```
 
-[View file →](src/libs/transform/wrapTextWithSpans.ts)
+[View file →](src/libs/transform/wrap-text-with-spans.ts)
 
 ## Wait
 
@@ -897,7 +963,7 @@ import { waitForAllMediaLoaded } from "umaki";
 })();
 ```
 
-[View file →](src/libs/wait/waitForAllMediaLoaded.ts)
+[View file →](src/libs/wait/wait-for-all-media-loaded.ts)
 
 ## Security
 
@@ -926,7 +992,145 @@ This function uses `isomorphic-dompurify` and has the following features:
 - Allows flexible control through custom configuration
 - Can be used on both server-side and client-side
 
-[View file →](src/libs/security/htmlSanitize.ts)
+[View file →](src/libs/security/html-sanitize.ts)
+
+## Advanced Usage
+
+This section provides tips and patterns for getting the most out of umaki utilities.
+
+### Using `tap` / `tapAsync` with umaki functions
+
+The `tap` and `tapAsync` functions allow you to add callbacks to any umaki function without modifying its behavior. This is useful for logging, analytics, caching, and more.
+
+#### Basic Pattern
+
+| Function Type | Use | Example |
+|---------------|-----|---------|
+| Sync (returns value) | `tap` | `tap(removeAllHtmlTags(input), callback)` |
+| Sync (returns void) | `tap` | `tap(set100vh(), callback)` |
+| Async (returns Promise) | `tapAsync` | `tapAsync(sleep(1), callback)` |
+
+> [!TIP]
+> `tap` prevents Promise values at the type level. If you accidentally pass a Promise, TypeScript will show an error.
+
+#### Examples with umaki functions
+
+<details>
+<summary><strong>📝 Logging & Debugging</strong></summary>
+
+```ts
+import { tap, removeAllHtmlTags, getUaData } from "umaki";
+
+// Log sanitized HTML output
+const clean = tap(removeAllHtmlTags(dirtyHtml), (result) => {
+  console.log("[DEBUG] Sanitized HTML:", result);
+});
+
+// Log user agent data
+const ua = tap(getUaData(), (data) => {
+  console.log("[DEBUG] UA:", data.browserName, data.osName);
+});
+```
+
+</details>
+
+<details>
+<summary><strong>📊 Analytics & Tracking</strong></summary>
+
+```ts
+import { tap, tapAsync, getUaData, waitForAllMediaLoaded } from "umaki";
+
+// Track device information
+const uaData = tap(getUaData(), (data) => {
+  analytics.track("device_detected", {
+    browser: data.browserName,
+    os: data.osName,
+    type: data.type,
+  });
+});
+
+// Track media load completion
+await tapAsync(waitForAllMediaLoaded(), (success) => {
+  analytics.track("media_loaded", { success, timestamp: Date.now() });
+});
+```
+
+</details>
+
+<details>
+<summary><strong>💾 Caching</strong></summary>
+
+```ts
+import { tap, tapAsync, getScrollbarWidth } from "umaki";
+
+// Cache scrollbar width (useful for repeated access)
+const scrollbarWidth = tap(getScrollbarWidth(), (width) => {
+  sessionStorage.setItem("scrollbarWidth", String(width));
+});
+
+// Cache async fetch results
+const getData = () =>
+  tapAsync(fetchFromAPI(), (data) => {
+    localStorage.setItem("cachedData", JSON.stringify(data));
+  });
+```
+
+</details>
+
+<details>
+<summary><strong>🎯 Event Emission</strong></summary>
+
+```ts
+import { tap, tapAsync, checkDeviceSize, waitForAllMediaLoaded } from "umaki";
+
+// Emit event on device size check
+const deviceSize = tap(checkDeviceSize(), (size) => {
+  window.dispatchEvent(new CustomEvent("deviceSizeChecked", { detail: size }));
+});
+
+// Emit event when all media is loaded
+await tapAsync(waitForAllMediaLoaded(true), () => {
+  window.dispatchEvent(new CustomEvent("firstViewMediaReady"));
+});
+```
+
+</details>
+
+<details>
+<summary><strong>⚡ Parallel Async Operations</strong></summary>
+
+```ts
+import { tapAsync, sleep, waitForAllMediaLoaded } from "umaki";
+
+// Track multiple async operations independently
+const [_, mediaLoaded] = await Promise.all([
+  tapAsync(sleep(1), () => console.log("⏱️ 1 second elapsed")),
+  tapAsync(waitForAllMediaLoaded(), (ok) => console.log("🖼️ Media:", ok ? "ready" : "failed")),
+]);
+```
+
+</details>
+
+#### Working with void functions
+
+> [!NOTE]
+> When using `tap` with functions that return `void` (like `set100vh`, `bgScrollStop`), the callback receives `undefined`. This is still useful for completion notifications.
+
+```ts
+import { tap, set100vh, bgScrollStop } from "umaki";
+
+// Notification when viewport units are set
+tap(set100vh(), () => {
+  console.log("✅ 100vh CSS variable has been set");
+});
+
+// Notification when scroll is stopped
+tap(bgScrollStop(true), () => {
+  console.log("🔒 Background scroll locked");
+});
+```
+
+---
 
 ## Using for framework and tools