@splendidlabz/utils 1.8.1 → 1.8.2

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/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++) {

package/src/lib/functions/functional.test.js

@@ -0,0 +1,196 @@
+import { describe, expect, it } from 'vitest'
+import {
+  compose,
+  composeAsync,
+  curry,
+  pipe,
+  pipeAsync,
+  times,
+} from './functional.js'
+
+describe('functional utilities', () => {
+  describe('curry', () => {
+    it('should curry a function with multiple arguments', () => {
+      const add = (a, b, c) => a + b + c
+      const curriedAdd = curry(add)
+
+      expect(curriedAdd(1)(2)(3)).toBe(6)
+      expect(curriedAdd(1, 2)(3)).toBe(6)
+      expect(curriedAdd(1)(2, 3)).toBe(6)
+      expect(curriedAdd(1, 2, 3)).toBe(6)
+    })
+  })
+
+  describe('compose (sync)', () => {
+    it('should compose functions from right to left', () => {
+      const add1 = x => x + 1
+      const multiply2 = x => x * 2
+      const composed = compose(add1, multiply2)
+
+      expect(composed(3)).toBe(7) // (3 * 2) + 1
+    })
+
+    it('should work with single function', () => {
+      const add1 = x => x + 1
+      const composed = compose(add1)
+
+      expect(composed(5)).toBe(6)
+    })
+
+    it('should work with multiple functions', () => {
+      const add1 = x => x + 1
+      const multiply2 = x => x * 2
+      const subtract3 = x => x - 3
+      const composed = compose(subtract3, add1, multiply2)
+
+      expect(composed(5)).toBe(8) // ((5 * 2) + 1) - 3 = 8
+    })
+  })
+
+  describe('composeAsync', () => {
+    it('should compose async functions from right to left', async () => {
+      const add1 = x => x + 1
+      const multiplyAsync = async x => x * 2
+
+      const result = await composeAsync(add1, multiplyAsync)(3)
+      expect(result).toBe(7) // (3 * 2) + 1
+    })
+
+    it('should work with all sync functions', async () => {
+      const add1 = x => x + 1
+      const multiply2 = x => x * 2
+
+      const result = await composeAsync(add1, multiply2)(3)
+      expect(result).toBe(7) // (3 * 2) + 1
+    })
+
+    it('should work with all async functions', async () => {
+      const add1Async = async x => x + 1
+      const multiply2Async = async x => x * 2
+
+      const result = await composeAsync(add1Async, multiply2Async)(3)
+      expect(result).toBe(7) // (3 * 2) + 1
+    })
+
+    it('should work with mixed sync and async functions', async () => {
+      const add1 = x => x + 1
+      const multiply2Async = async x => x * 2
+      const subtract3 = x => x - 3
+
+      const result = await composeAsync(subtract3, add1, multiply2Async)(5)
+      expect(result).toBe(8) // ((5 * 2) + 1) - 3 = 8
+    })
+  })
+
+  describe('pipe (sync)', () => {
+    it('should pipe functions from left to right', () => {
+      const add1 = x => x + 1
+      const multiply2 = x => x * 2
+      const piped = pipe(add1, multiply2)
+
+      expect(piped(3)).toBe(8) // (3 + 1) * 2
+    })
+
+    it('should work with single function', () => {
+      const add1 = x => x + 1
+      const piped = pipe(add1)
+
+      expect(piped(5)).toBe(6)
+    })
+
+    it('should work with multiple functions', () => {
+      const add1 = x => x + 1
+      const multiply2 = x => x * 2
+      const subtract3 = x => x - 3
+      const piped = pipe(add1, multiply2, subtract3)
+
+      expect(piped(5)).toBe(9) // ((5 + 1) * 2) - 3 = 9
+    })
+  })
+
+  describe('pipeAsync', () => {
+    it('should pipe async functions from left to right', async () => {
+      const add1 = x => x + 1
+      const multiplyAsync = async x => x * 2
+
+      const result = await pipeAsync(add1, multiplyAsync)(3)
+      expect(result).toBe(8) // (3 + 1) * 2
+    })
+
+    it('should work with all sync functions', async () => {
+      const add1 = x => x + 1
+      const multiply2 = x => x * 2
+
+      const result = await pipeAsync(add1, multiply2)(3)
+      expect(result).toBe(8) // (3 + 1) * 2
+    })
+
+    it('should work with all async functions', async () => {
+      const add1Async = async x => x + 1
+      const multiply2Async = async x => x * 2
+
+      const result = await pipeAsync(add1Async, multiply2Async)(3)
+      expect(result).toBe(8) // (3 + 1) * 2
+    })
+
+    it('should work with mixed sync and async functions', async () => {
+      const add1 = x => x + 1
+      const multiply2Async = async x => x * 2
+      const subtract3 = x => x - 3
+
+      const result = await pipeAsync(add1, multiply2Async, subtract3)(5)
+      expect(result).toBe(9) // ((5 + 1) * 2) - 3 = 9
+    })
+
+    it('should handle promises in the pipeline', async () => {
+      const asyncAdd = async x => {
+        await new Promise(resolve => setTimeout(resolve, 1))
+        return x + 1
+      }
+      const multiply2 = x => x * 2
+
+      const result = await pipeAsync(asyncAdd, multiply2)(3)
+      expect(result).toBe(8) // (3 + 1) * 2
+    })
+  })
+
+  describe('times', () => {
+    it('should call function n times with index', () => {
+      const result = times(i => i * 2, 3)
+      expect(result).toEqual([0, 2, 4])
+    })
+
+    it('should work with zero iterations', () => {
+      const result = times(i => i, 0)
+      expect(result).toEqual([])
+    })
+
+    it('should work with functions that ignore index', () => {
+      const result = times(() => 'hello', 2)
+      expect(result).toEqual(['hello', 'hello'])
+    })
+  })
+
+  // Edge cases and error handling
+  describe('edge cases', () => {
+    it('should handle empty function arrays in compose', () => {
+      const composed = compose()
+      expect(composed(5)).toBe(5)
+    })
+
+    it('should handle empty function arrays in pipe', () => {
+      const piped = pipe()
+      expect(piped(5)).toBe(5)
+    })
+
+    it('should handle empty function arrays in composeAsync', async () => {
+      const result = await composeAsync()(5)
+      expect(result).toBe(5)
+    })
+
+    it('should handle empty function arrays in pipeAsync', async () => {
+      const result = await pipeAsync()(5)
+      expect(result).toBe(5)
+    })
+  })
+})