@splendidlabz/utils 1.7.0 → 1.8.2

package/dist/esm/lib/objects/extend.js

@@ -24,8 +24,9 @@ function curry(fn) {
 }
 
 // src/lib/objects/mix/mix.js
-var DEFAULT_OPTIONS = { array: "concat" };
+var DEFAULT_OPTIONS = { array: "replace" };
 var mix = createMix();
+var concatMix = createMix({ array: "concat" });
 function createMix(userOptions = {}) {
   const options = { ...DEFAULT_OPTIONS, ...userOptions };
   function _mix(...sources) {

package/dist/esm/lib/objects/index.js

@@ -94,8 +94,9 @@ function pipe(...fns) {
 }
 
 // src/lib/objects/mix/mix.js
-var DEFAULT_OPTIONS = { array: "concat" };
+var DEFAULT_OPTIONS = { array: "replace" };
 var mix = createMix();
+var concatMix = createMix({ array: "concat" });
 function createMix(userOptions = {}) {
   const options = { ...DEFAULT_OPTIONS, ...userOptions };
   function _mix(...sources) {
@@ -300,6 +301,7 @@ function splitObject(obj, keys) {
 }
 export {
   camelCaseKeys,
+  concatMix,
   createMix,
   extendObject,
   flattenObject,

package/dist/esm/lib/objects/mix/mix.js

@@ -1,6 +1,7 @@
 // src/lib/objects/mix/mix.js
-var DEFAULT_OPTIONS = { array: "concat" };
+var DEFAULT_OPTIONS = { array: "replace" };
 var mix = createMix();
+var concatMix = createMix({ array: "concat" });
 function createMix(userOptions = {}) {
   const options = { ...DEFAULT_OPTIONS, ...userOptions };
   function _mix(...sources) {
@@ -82,6 +83,7 @@ function objectType(value) {
   return Object.prototype.toString.call(value);
 }
 export {
+  concatMix,
   createMix,
   mix
 };

package/dist/esm/node/file-cache.js

@@ -1,6 +1,6 @@
 // src/node/file-cache.js
 import fs from "fs/promises";
-import glob from "glob-promise";
+import { glob } from "glob";
 import path from "path";
 
 // src/lib/objects/nested-property.js

package/dist/esm/node/index.js

@@ -17,7 +17,7 @@ function dirname(url) {
 
 // src/node/file-cache.js
 import fs from "fs/promises";
-import glob from "glob-promise";
+import { glob } from "glob";
 import path2 from "path";
 
 // src/lib/objects/nested-property.js

package/dist/types/dom/index.d.cts

@@ -17,6 +17,7 @@ export { imagesLoaded, mediaLoaded, videosLoaded } from './media.cjs';
 export { intersectionObserver } from './observers/intersection-observer.cjs';
 export { mutationObserver } from './observers/mutation-observer.cjs';
 export { resizeObserver } from './observers/resize-observer.cjs';
+export { scrollObserver } from './observers/scroll-observer.cjs';
 export { PKCE } from './pkce.cjs';
 export { queryParams } from './query-params.cjs';
 export { randomString, uuid } from './random-string.cjs';

package/dist/types/dom/observers/index.d.cts

@@ -1,3 +1,4 @@
 export { intersectionObserver } from './intersection-observer.cjs';
 export { mutationObserver } from './mutation-observer.cjs';
 export { resizeObserver } from './resize-observer.cjs';
+export { scrollObserver } from './scroll-observer.cjs';

package/dist/types/dom/observers/scroll-observer.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Scroll Observer - Optimized for performance
+ * @param {Element} node - The element to observe scroll events on
+ * @param {Object} options - Configuration options
+ * @param {Number} options.threshold - Float between 0 to 1. When to trigger callback (0.75 = 75% down page)
+ * @param {Number} options.tolerance - Float between 0 to 1. Tolerance zone around threshold
+ * @param {Number} options.throttle - Throttle interval in ms (default: 16ms for ~60fps)
+ * @param {Boolean} options.once - Only fire threshold callback once (default: false)
+ * @param {Function} options.callback - Called on every scroll with scrollPercent
+ * @param {Function} options.onScrollDown - Called when scrolling down
+ * @param {Function} options.onScrollUp - Called when scrolling up
+ * @param {Function} options.onEnterThreshold - Called when entering threshold zone
+ */
+declare function scrollObserver(node: Element, options?: {
+    threshold: number;
+    tolerance: number;
+    throttle: number;
+    once: boolean;
+    callback: Function;
+    onScrollDown: Function;
+    onScrollUp: Function;
+    onEnterThreshold: Function;
+}): {
+    destroy(): void;
+};
+
+export { scrollObserver };

package/dist/types/lib/functions/functional.d.cts

@@ -1,6 +1,72 @@
-declare function curry(fn: any): (...args: any[]) => any;
-declare function compose(...fns: any[]): (value: any) => any;
-declare function pipe(...fns: any[]): (value: any) => any;
-declare function times(fn: any, n: any): any[];
+/**
+ * Creates a curried version of a function that can be called with partial arguments
+ * @param {Function} fn - The function to curry
+ * @return {Function} The curried function
+ * @property {any} return - The result of calling the original function when all arguments are provided
+ * @example
+ * const add = (a, b, c) => a + b + c
+ * const curriedAdd = curry(add)
+ * curriedAdd(1)(2)(3) // 6
+ * curriedAdd(1, 2)(3) // 6
+ * curriedAdd(1)(2, 3) // 6
+ */
+declare function curry(fn: Function): Function;
+/**
+ * Composes functions from right to left (synchronous)
+ * @param {...Function} fns - Functions to compose
+ * @return {Function} The composed function
+ * @property {any} return - The result of applying all functions in sequence
+ * @example
+ * const add1 = x => x + 1
+ * const multiply2 = x => x * 2
+ * const composed = compose(add1, multiply2)
+ * composed(3) // 7 (3 * 2 + 1)
+ */
+declare function compose(...fns: Function[]): Function;
+/**
+ * Composes functions from right to left (asynchronous)
+ * @param {...Function} fns - Functions to compose (can be sync or async)
+ * @return {Function} The composed async function
+ * @property {Promise<any>} return - A Promise that resolves to the result of applying all functions
+ * @example
+ * const add1 = x => x + 1
+ * const multiplyAsync = async x => x * 2
+ * await composeAsync(add1, multiplyAsync)(3) // 7 (3 * 2 + 1)
+ */
+declare function composeAsync(...fns: Function[]): Function;
+/**
+ * Pipes functions from left to right (synchronous)
+ * @param {...Function} fns - Functions to pipe
+ * @return {Function} The piped function
+ * @property {any} return - The result of applying all functions in sequence
+ * @example
+ * const add1 = x => x + 1
+ * const multiply2 = x => x * 2
+ * const piped = pipe(add1, multiply2)
+ * piped(3) // 8 (3 + 1) * 2
+ */
+declare function pipe(...fns: Function[]): Function;
+/**
+ * Pipes functions from left to right (asynchronous)
+ * @param {...Function} fns - Functions to pipe (can be sync or async)
+ * @return {Function} The piped async function
+ * @property {Promise<any>} return - A Promise that resolves to the result of applying all functions
+ * @example
+ * const add1 = x => x + 1
+ * const multiplyAsync = async x => x * 2
+ * await pipeAsync(add1, multiplyAsync)(3) // 8 ((3 + 1) * 2)
+ */
+declare function pipeAsync(...fns: Function[]): Function;
+/**
+ * Calls a function n times with the current index and returns an array of results
+ * @param {Function} fn - Function to call (receives index as argument)
+ * @param {number} n - Number of times to call the function
+ * @return {any[]} Array of results from calling the function
+ * @property {any[]} return - Array containing the results of each function call
+ * @example
+ * times(i => i * 2, 3) // [0, 2, 4]
+ * times(() => Math.random(), 2) // [0.123, 0.456] (random values)
+ */
+declare function times(fn: Function, n: number): any[];
 
-export { compose, curry, pipe, times };
+export { compose, composeAsync, curry, pipe, pipeAsync, times };

package/dist/types/lib/functions/index.d.cts

@@ -1,5 +1,5 @@
 export { debounce } from './debounce.cjs';
 export { getEnv } from './env.cjs';
-export { compose, curry, pipe, times } from './functional.cjs';
+export { compose, composeAsync, curry, pipe, pipeAsync, times } from './functional.cjs';
 export { throttle } from './throttle.cjs';
 export { delay, timeout, wait } from './timeout.cjs';

package/dist/types/lib/index.d.cts

@@ -13,7 +13,7 @@ export { flattenArrayFields, formDataToObject } from './form/form-data.cjs';
 export { SanitizeOptions, sanitize, sanitizeArray, sanitizeObject } from './form/sanitize.cjs';
 export { debounce } from './functions/debounce.cjs';
 export { getEnv } from './functions/env.cjs';
-export { compose, curry, pipe, times } from './functions/functional.cjs';
+export { compose, composeAsync, curry, pipe, pipeAsync, times } from './functions/functional.cjs';
 export { throttle } from './functions/throttle.cjs';
 export { delay, timeout, wait } from './functions/timeout.cjs';
 export { isHashedValue } from './hash.cjs';
@@ -25,7 +25,7 @@ export { extendObject } from './objects/extend.cjs';
 export { flattenObject } from './objects/flatten.cjs';
 export { parseJSON } from './objects/json.cjs';
 export { objectForEach, objectMap } from './objects/loop.cjs';
-export { createMix, mix } from './objects/mix/mix.cjs';
+export { concatMix, createMix, mix } from './objects/mix/mix.cjs';
 export { getNestedProperty, getNestedProperty2, getNestedValue } from './objects/nested-property.cjs';
 export { normalizeObject } from './objects/normalize-object.cjs';
 export { omitEmpty } from './objects/omit-empty.cjs';

package/dist/types/lib/objects/extend.d.cts

@@ -1,6 +1,6 @@
 declare function extendObject(object: any): {
     orig: any;
-    extended: {};
+    extended: any;
 };
 
 export { extendObject };

package/dist/types/lib/objects/index.d.cts

@@ -5,7 +5,7 @@ export { extendObject } from './extend.cjs';
 export { flattenObject } from './flatten.cjs';
 export { parseJSON } from './json.cjs';
 export { objectForEach, objectMap } from './loop.cjs';
-export { createMix, mix } from './mix/mix.cjs';
+export { concatMix, createMix, mix } from './mix/mix.cjs';
 export { getNestedProperty, getNestedProperty2, getNestedValue } from './nested-property.cjs';
 export { normalizeObject } from './normalize-object.cjs';
 export { omitEmpty } from './omit-empty.cjs';

package/dist/types/lib/objects/mix/mix.d.cts

@@ -1,4 +1,44 @@
-declare function createMix(userOptions?: {}): (...sources: any[]) => {};
-declare function mix(...sources: any[]): {};
+/**
+ * Creates a customized mix function with specific options for array handling.
+ *
+ * @param {Object} [userOptions={}] - Configuration options for the mix function.
+ * @param {('replace'|'concat')} [userOptions.array='replace'] - How to handle array merging:
+ *   - 'replace': Arrays from later sources completely replace arrays from earlier sources
+ *   - 'concat': Arrays are concatenated together
+ * @return {Function} A mix function configured with the provided options.
+ *
+ * @example
+ * // Create mix function that concatenates arrays
+ * const concatMix = createMix({ array: 'concat' })
+ * const obj1 = { items: [1, 2] }
+ * const obj2 = { items: [3, 4] }
+ * const result = concatMix(obj1, obj2)
+ * // Returns: { items: [1, 2, 3, 4] }
+ *
+ * @example
+ * // Create mix function that replaces arrays (default behavior)
+ * const replaceMix = createMix({ array: 'replace' })
+ * const obj1 = { items: [1, 2] }
+ * const obj2 = { items: [3, 4] }
+ * const result = replaceMix(obj1, obj2)
+ * // Returns: { items: [3, 4] }
+ */
+declare function createMix(userOptions?: {
+    array?: ("replace" | "concat");
+}): Function;
+/**
+ * Deep merges multiple objects into a new object with intelligent handling of arrays and nested objects.
+ *
+ * @param {...Object} sources - Objects to merge. Null and undefined values are skipped.
+ * @return {Object} A new object containing the merged properties from all sources.
+ *
+ * @example
+ * const obj1 = { a: 1, b: { x: 10 } }
+ * const obj2 = { b: { y: 20 }, c: 3 }
+ * const result = mix(obj1, obj2)
+ * // Returns: { a: 1, b: { x: 10, y: 20 }, c: 3 }
+ */
+declare const mix: Function;
+declare const concatMix: Function;
 
-export { createMix, mix };
+export { concatMix, createMix, mix };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splendidlabz/utils",
-  "version": "1.7.0",
+  "version": "1.8.2",
   "description": "",
   "type": "module",
   "sideEffects": false,
@@ -53,7 +53,7 @@
   "dependencies": {
     "deep-eql": "^5.0.2",
     "dompurify": "^3.2.4",
-    "glob-promise": "^6.0.7",
+    "glob": "^11.0.0",
     "marked": "^15.0.7",
     "marked-gfm-heading-id": "^4.1.1",
     "marked-mangle": "^1.1.10",
@@ -63,7 +63,6 @@
   },
   "devDependencies": {
     "@splendidlabz/eslint-config": "2.1.0",
-    "glob": "^11.0.0",
     "jsdom": "^26.0.0",
     "np": "^10.2.0",
     "tsup": "^8.0.0",

package/src/dom/observers/index.js

@@ -1,3 +1,4 @@
 export * from './intersection-observer.js'
 export * from './mutation-observer.js'
 export * from './resize-observer.js'
+export * from './scroll-observer.js'

package/src/dom/observers/resize-observer.js

@@ -4,8 +4,8 @@ import { useObserverMethodOnTarget } from './observer.js'
 
 /**
  * Creates and manages a ResizeObserver instance to monitor size changes of a target element.
- * 
- * @param {Element|Window|NodeList|Element[]} target - The element(s) to observe. 
+ *
+ * @param {Element|Window|NodeList|Element[]} target - The element(s) to observe.
  *   - If window is provided, document.body will be observed instead.
  *   - If NodeList or Array of elements is provided, all elements will be observed.
  * @param {Object} options - Configuration options for the resize observer
@@ -13,13 +13,13 @@ import { useObserverMethodOnTarget } from './observer.js'
  * @param {Function} [options.callback] - Optional callback function that will be called when resize changes are detected.
  *                                          If not provided, a 'resize-obs' event will be dispatched on the target.
  * @param {Object} [options.observerOptions] - Additional options to pass to ResizeObserver.observe()
- * 
+ *
  * @returns {Object} An object with methods to control the observer:
  *   - observe(target, options): Start observing a new target element
  *   - unobserve(target): Stop observing a target element
  *   - disconnect(): Disconnect the observer and stop all observations
  *   - destroy(): Alias for disconnect()
- * 
+ *
  * @example
  * // Basic usage with callback
  * resizeObserver(element, {
@@ -27,7 +27,7 @@ import { useObserverMethodOnTarget } from './observer.js'
  *     console.log('Element resized:', entry.contentRect);
  *   }
  * });
- * 
+ *
  * @example
  * // Usage with event listener
  * resizeObserver(element);

package/src/dom/observers/scroll-observer.js

@@ -0,0 +1,132 @@
+/* eslint-env browser */
+import { resizeObserver } from './resize-observer.js'
+
+const defaultOptions = {
+  threshold: 0, // Float between 0 to 1.
+  tolerance: 0.1, // Float between 0 to 1. Tolerance for event firing
+  throttle: 16, // Throttle interval in ms (default: ~60fps)
+  once: false, // Only fire threshold callback once
+}
+
+// TODO: Move to Utils/Dom
+/**
+ * Scroll Observer - Optimized for performance
+ * @param {Element} node - The element to observe scroll events on
+ * @param {Object} options - Configuration options
+ * @param {Number} options.threshold - Float between 0 to 1. When to trigger callback (0.75 = 75% down page)
+ * @param {Number} options.tolerance - Float between 0 to 1. Tolerance zone around threshold
+ * @param {Number} options.throttle - Throttle interval in ms (default: 16ms for ~60fps)
+ * @param {Boolean} options.once - Only fire threshold callback once (default: false)
+ * @param {Function} options.callback - Called on every scroll with scrollPercent
+ * @param {Function} options.onScrollDown - Called when scrolling down
+ * @param {Function} options.onScrollUp - Called when scrolling up
+ * @param {Function} options.onEnterThreshold - Called when entering threshold zone
+ */
+export function scrollObserver(node, options = {}) {
+  const { callback, onScrollDown, onScrollUp, onEnterThreshold, ...userOpts } =
+    options
+  const opts = { ...defaultOptions, ...userOpts }
+  const { threshold, tolerance, throttle, once } = opts
+
+  const prevScrollDirection = null
+  let prevScrollTop = 0
+  let prevScrollPercent = 0
+  let lastThrottleTime = 0
+  let thresholdFired = false
+  let rafId = null
+
+  // Determine scroll context once at initialization
+  const isDocumentScroll = node === document || node === window
+  const scrollElement = isDocumentScroll ? document.documentElement : node
+
+  // Cache DOM references and expensive calculations
+  let cachedScrollHeight = 0
+  let cachedClientHeight = 0
+
+  // Initialize cache and start observing for changes
+  updateCache()
+  const cacheObserver = resizeObserver(scrollElement, {
+    callback: updateCache,
+  })
+
+  node.addEventListener('scroll', throttledObserve, { passive: true })
+
+  function updateCache() {
+    cachedScrollHeight = scrollElement.scrollHeight
+    cachedClientHeight = scrollElement.clientHeight
+  }
+
+  function throttledObserve() {
+    const now = Date.now()
+    if (now - lastThrottleTime < throttle) return
+
+    lastThrottleTime = now
+    rafId = requestAnimationFrame(observe)
+  }
+
+  function observe() {
+    const scrollTop = scrollElement.scrollTop
+
+    // Skip if scroll position hasn't changed meaningfully
+    if (Math.abs(scrollTop - prevScrollTop) < 1) return
+
+    const scrollDirection = scrollTop > prevScrollTop ? 'down' : 'up'
+    const maxScroll = Math.max(1, cachedScrollHeight - cachedClientHeight)
+    const scrollPercent = Math.min(1, Math.max(0, scrollTop / maxScroll))
+
+    // Check threshold crossing (e.g., 75% ± tolerance)
+    const thresholdMin = threshold - tolerance / 2
+    const thresholdMax = threshold + tolerance / 2
+    const wasInThreshold =
+      prevScrollPercent >= thresholdMin && prevScrollPercent <= thresholdMax
+    const isInThreshold =
+      scrollPercent >= thresholdMin && scrollPercent <= thresholdMax
+    const hasEnteredThreshold =
+      !wasInThreshold && isInThreshold && (!once || !thresholdFired)
+
+    if (hasEnteredThreshold && once) {
+      thresholdFired = true
+    }
+
+    // Prepare common data for all callbacks
+    const callbackData = {
+      scrollTop,
+      scrollDirection,
+      scrollPercent,
+      directionChanged: scrollDirection !== prevScrollDirection,
+      hasEnteredThreshold,
+      isInThreshold,
+    }
+
+    // Call specific callbacks
+    if (typeof callback === 'function') {
+      callback(callbackData)
+    }
+
+    // Only fire direction callbacks when direction actually changes
+    if (scrollDirection !== prevScrollDirection) {
+      if (scrollDirection === 'down' && typeof onScrollDown === 'function') {
+        onScrollDown(callbackData)
+      }
+      if (scrollDirection === 'up' && typeof onScrollUp === 'function') {
+        onScrollUp(callbackData)
+      }
+    }
+
+    // Fire threshold callback when entering threshold zone
+    if (hasEnteredThreshold && typeof onEnterThreshold === 'function') {
+      onEnterThreshold(callbackData)
+    }
+
+    prevScrollTop = scrollTop
+    prevScrollPercent = scrollPercent
+  }
+
+  return {
+    destroy() {
+      node.removeEventListener('scroll', throttledObserve)
+      if (rafId) cancelAnimationFrame(rafId)
+      cacheObserver.destroy()
+    },
+  }
+}

package/src/lib/date/time.js

@@ -16,10 +16,12 @@ export function ms(arg) {
   if (unit === 'hours') return getTimeInMs(value, 'hours')
   if (unit === 'm') return getTimeInMs(value, 'minutes')
   if (unit === 'min') return getTimeInMs(value, 'minutes')
+  if (unit === 'mins') return getTimeInMs(value, 'minutes')
   if (unit === 'minute') return getTimeInMs(value, 'minutes')
   if (unit === 'minutes') return getTimeInMs(value, 'minutes')
   if (unit === 's') return getTimeInMs(value, 'seconds')
   if (unit === 'sec') return getTimeInMs(value, 'seconds')
+  if (unit === 'secs') return getTimeInMs(value, 'seconds')
   if (unit === 'second') return getTimeInMs(value, 'seconds')
   if (unit === 'seconds') return getTimeInMs(value, 'seconds')
 

package/src/lib/functions/functional.js

@@ -1,3 +1,15 @@
+/**
+ * Creates a curried version of a function that can be called with partial arguments
+ * @param {Function} fn - The function to curry
+ * @return {Function} The curried function
+ * @property {any} return - The result of calling the original function when all arguments are provided
+ * @example
+ * const add = (a, b, c) => a + b + c
+ * const curriedAdd = curry(add)
+ * curriedAdd(1)(2)(3) // 6
+ * curriedAdd(1, 2)(3) // 6
+ * curriedAdd(1)(2, 3) // 6
+ */
 export function curry(fn) {
   return function curried(...args) {
     if (args.length >= fn.length) {
@@ -10,18 +22,88 @@ export function curry(fn) {
   }
 }
 
+/**
+ * Composes functions from right to left (synchronous)
+ * @param {...Function} fns - Functions to compose
+ * @return {Function} The composed function
+ * @property {any} return - The result of applying all functions in sequence
+ * @example
+ * const add1 = x => x + 1
+ * const multiply2 = x => x * 2
+ * const composed = compose(add1, multiply2)
+ * composed(3) // 7 (3 * 2 + 1)
+ */
 export function compose(...fns) {
   return function (value) {
     return fns.reduceRight((acc, fn) => fn(acc), value)
   }
 }
 
+/**
+ * Composes functions from right to left (asynchronous)
+ * @param {...Function} fns - Functions to compose (can be sync or async)
+ * @return {Function} The composed async function
+ * @property {Promise<any>} return - A Promise that resolves to the result of applying all functions
+ * @example
+ * const add1 = x => x + 1
+ * const multiplyAsync = async x => x * 2
+ * await composeAsync(add1, multiplyAsync)(3) // 7 (3 * 2 + 1)
+ */
+export function composeAsync(...fns) {
+  return async function (value) {
+    return fns.reduceRight(async (acc, fn) => {
+      const result = await acc
+      return await fn(result)
+    }, value)
+  }
+}
+
+/**
+ * Pipes functions from left to right (synchronous)
+ * @param {...Function} fns - Functions to pipe
+ * @return {Function} The piped function
+ * @property {any} return - The result of applying all functions in sequence
+ * @example
+ * const add1 = x => x + 1
+ * const multiply2 = x => x * 2
+ * const piped = pipe(add1, multiply2)
+ * piped(3) // 8 (3 + 1) * 2
+ */
 export function pipe(...fns) {
   return function (value) {
     return fns.reduce((acc, fn) => fn(acc), value)
   }
 }
 
+/**
+ * Pipes functions from left to right (asynchronous)
+ * @param {...Function} fns - Functions to pipe (can be sync or async)
+ * @return {Function} The piped async function
+ * @property {Promise<any>} return - A Promise that resolves to the result of applying all functions
+ * @example
+ * const add1 = x => x + 1
+ * const multiplyAsync = async x => x * 2
+ * await pipeAsync(add1, multiplyAsync)(3) // 8 ((3 + 1) * 2)
+ */
+export function pipeAsync(...fns) {
+  return async function (value) {
+    return fns.reduce(async (acc, fn) => {
+      const result = await acc
+      return await fn(result)
+    }, value)
+  }
+}
+
+/**
+ * Calls a function n times with the current index and returns an array of results
+ * @param {Function} fn - Function to call (receives index as argument)
+ * @param {number} n - Number of times to call the function
+ * @return {any[]} Array of results from calling the function
+ * @property {any[]} return - Array containing the results of each function call
+ * @example
+ * times(i => i * 2, 3) // [0, 2, 4]
+ * times(() => Math.random(), 2) // [0.123, 0.456] (random values)
+ */
 export function times(fn, n) {
   const result = []
   for (let i = 0; i < n; i++) {