@planet-matrix/mobius-model 0.3.0 → 0.4.0

package/src/basic/function.ts

@@ -0,0 +1,453 @@
+import type {
+  AnyAsyncFunction,
+  AnyFunction,
+  FunctionComposeAll,
+  FunctionPipeAll,
+} from "#Source/type/index.ts"
+
+import { asIs } from "./helper.ts"
+import { isAsyncFunction, isSyncFunction } from "./is.ts"
+
+/**
+ * Immediately invoke a function with the provided arguments.
+ *
+ * @example
+ * ```
+ * // Expect: 3
+ * const example1 = functionIife((a: number, b: number) => a + b, 1, 2)
+ * // Expect: "ok"
+ * const example2 = functionIife(() => "ok")
+ * ```
+ */
+export const functionIife = <T extends AnyFunction>(
+  fn: T, ...args: Parameters<T>
+): ReturnType<T> => {
+  // oxlint-disable-next-line no-unsafe-return
+  return fn(...args)
+}
+
+export type FunctionOnce<T extends AnyFunction> =
+  (...args: Parameters<T>) => ReturnType<T>
+/**
+ * Generate a one-off function for a given function.
+ *
+ * @example
+ * ```
+ * const onceFn = functionOnce((x) => x * 2)
+ * // Will return 10
+ * const result1 = onceFn(5)
+ * // Will still return 10, original function will not be called again
+ * const result2 = onceFn(10)
+ * // If timesSubscriber is provided, it will be called with the number of calls after the second call
+ * let callCount = 0
+ * const onceFnWithSubscriber = functionOnce((x) => x * 2, (times) => { callCount = times })
+ * onceFnWithSubscriber(5) // callCount is still 0
+ * onceFnWithSubscriber(10) // callCount becomes 2
+ * ```
+ */
+export const functionOnce = <T extends AnyFunction>(
+  fn: T,
+  timesSubscriber?: (times: number) => void,
+): FunctionOnce<T> => {
+  let called = false
+  let result: ReturnType<typeof fn>
+  let times = 0
+  return (...args) => {
+    times = times + 1
+    if (called === false) {
+      // oxlint-disable-next-line no-unsafe-assignment
+      result = fn(...args)
+      called = true
+    }
+    if (times >= 2 && timesSubscriber !== undefined) {
+      timesSubscriber(times)
+    }
+    // oxlint-disable-next-line no-unsafe-return
+    return result
+  }
+}
+
+export type FunctionDebouncedSimple<T extends AnyFunction> =
+  (...args: Parameters<T>) => void
+/**
+ * Generate a simple debounced function that delays invoking
+ * the original function until after a specified wait time
+ * has elapsed since the last time the debounced function was called.
+ *
+ * @example
+ * ```
+ * const debouncedFn = functionDebounceSimple((x) => console.log(x), 100)
+ * // Will log 5 after 100ms
+ * debouncedFn(5)
+ * // Will not log anything, will reset the timer
+ * debouncedFn(10)
+ * ```
+ */
+export const functionDebounceSimple = <T extends AnyFunction>(
+  fn: T,
+  ms: number
+): FunctionDebouncedSimple<T> => {
+  let timer: NodeJS.Timeout
+  return (...args) => {
+    clearTimeout(timer)
+    timer = setTimeout(() => {
+      fn(...args)
+    }, ms)
+  }
+}
+
+export type FunctionDebounced<T extends AnyFunction>
+  = (...args: Parameters<T>) => Promise<ReturnType<T>>
+/**
+ * Generate a debounced function that returns a promise resolving
+ * to the result of the original function. If the debounced function is called
+ * multiple times within the debounce period, it will only execute the original
+ * function once, and all calls will receive the same result.
+ *
+ * @example
+ * ```
+ * const debouncedFn = debounce(async (x) => x * 2, 100)
+ * // Will execute the original function after 100ms
+ * const result1 = debouncedFn(5)
+ * // Will not execute the original function, will receive the same result as result1
+ * const result2 = debouncedFn(10)
+ * // After 100ms, both result1 and result2 will resolve to 10
+ * ```
+ */
+export const debounce = <T extends AnyFunction>(
+  fn: T,
+  ms: number
+): FunctionDebounced<T> => {
+  let timer: NodeJS.Timeout
+  let waiting: AnyFunction[] = []
+  return async (...args) => {
+    clearTimeout(timer)
+    timer = setTimeout((async () => {
+      // oxlint-disable-next-line no-unsafe-assignment
+      const res = await fn(...args)
+      waiting.forEach((resolve) => {
+        resolve(res)
+      })
+      waiting = []
+    }) as (() => void), ms)
+
+    // oxlint-disable-next-line no-unsafe-return
+    return await new Promise((resolve) => {
+      waiting.push(resolve)
+    })
+  }
+}
+
+const THROTTLE_TYPE_ERROR = new TypeError("Throttle: fn must be a SyncFunction or AsyncFunction")
+export type FunctionThrottleTimeSimple<T extends AnyFunction> =
+  (...args: Parameters<T>) => void
+/**
+ * Generate a simple throttled function that only invokes the original function at most
+ * once per every specified milliseconds. The throttled function will execute the original
+ * function immediately on the first call, and then ignore subsequent calls until the
+ * specified time has elapsed.
+ *
+ * If `strict` is set to true, the throttled function will ensure that the window of time
+ * during which the original function can be invoked is greater than the sum of the
+ * specified milliseconds and the execution time of the original function.
+ *
+ * @example
+ * ```
+ * let called = 0
+ * const throttled = functionThrottleTimeSimple(() => { called += 1 }, 100)
+ * throttled()
+ * throttled()
+ * // Expect: called === 1
+ * const example1 = called
+ * ```
+ */
+export const functionThrottleTimeSimple = <T extends AnyFunction>(
+  fn: T,
+  ms: number,
+  strict = false
+): FunctionThrottleTimeSimple<T> => {
+  let isCalling = false
+  // NOTE: 对于不同的目标函数，分别返回不同的结果，避免在每次运行时再做条件判断。
+  if (isSyncFunction(fn) === true) {
+    return (...args) => {
+      if (isCalling === false) {
+        isCalling = true
+        setTimeout(() => {
+          isCalling = false
+        }, ms)
+        fn(...args)
+      }
+    }
+  }
+  else if (isAsyncFunction(fn) === true) {
+    return (...args) => {
+      let isExecuted = false
+      let timerExpired = false
+      if (isCalling === false) {
+        isCalling = true
+        setTimeout(() => {
+          if (strict === false) {
+            isCalling = false
+          }
+          else {
+            if (isExecuted === true) {
+              isCalling = false
+            }
+            else {
+              timerExpired = true
+            }
+          }
+        }, ms);
+        ; void (fn as AnyAsyncFunction)(...args).finally(() => {
+          isExecuted = true
+          if (timerExpired === true) {
+            isCalling = false
+          }
+        })
+      }
+    }
+  }
+  else {
+    throw THROTTLE_TYPE_ERROR
+  }
+}
+
+export type FunctionThrottleSimple<T extends AnyFunction> =
+  (...args: Parameters<T>) => void
+/**
+ * Generate a throttled function that only invokes the original function
+ * when it is not currently executing.
+ *
+ * @example
+ * ```
+ * let called = 0
+ * const throttled = functionThrottleSimple(() => { called += 1 })
+ * throttled()
+ * throttled()
+ * // Expect: called === 1
+ * const example1 = called
+ * ```
+ */
+export const functionThrottleSimple = <T extends AnyFunction>(
+  fn: T
+): FunctionThrottleSimple<T> => {
+  let isCalling = false
+  if (isSyncFunction(fn) === true) {
+    return (...args) => {
+      if (isCalling === false) {
+        isCalling = true
+        fn(...args)
+        isCalling = false
+      }
+    }
+  }
+  else if (isAsyncFunction(fn) === true) {
+    return (...args) => {
+      if (isCalling === false) {
+        isCalling = true;
+        ; void (fn as AnyAsyncFunction)(...args).then(() => {
+          isCalling = false
+        })
+      }
+    }
+  }
+  else {
+    throw THROTTLE_TYPE_ERROR
+  }
+}
+
+export type FunctionThrottleTime<T extends AnyFunction> =
+  (...args: Parameters<T>) => Promise<ReturnType<T>>
+/**
+ * Generate a throttled function that returns a promise resolving to the result
+ * of the original function. The throttled function will ensure that the original
+ * function is invoked at most once per every specified milliseconds.
+ *
+ * If `strict` is set to true, the window of time during which the original function
+ * can be invoked will be greater than the sum of the specified milliseconds and
+ * the execution time of the original function.
+ *
+ * @example
+ * ```
+ * const throttled = throttleTime(async (value: number) => value * 2, 100)
+ * const result1 = throttled(2)
+ * const result2 = throttled(3)
+ * // Expect: result1 and result2 resolve to 4
+ * ```
+ */
+export const throttleTime = <T extends AnyFunction>(
+  fn: T,
+  ms: number,
+  strict = false
+): FunctionThrottleTime<T> => {
+  let isCalling = false
+  let waiting: AnyFunction[] = []
+  return async (...args) => {
+    let isExecuted = false
+    let timerExpired = false
+    if (isCalling === false) {
+      isCalling = true
+      setTimeout(() => {
+        if (strict === false) {
+          isCalling = false
+        }
+        else {
+          if (isExecuted === true) {
+            isCalling = false
+          }
+          else {
+            timerExpired = true
+          }
+        }
+      }, ms)
+      // NOTE: 一般来说，如果目标函数是同步函数，节流版本也会同步执行，
+      // 如果是异步函数，节流版本会异步运行，
+      // 需要拿到结果的节流版本一律按照异步处理。
+      void Promise.resolve(fn(...args)).then((res) => {
+        // 先广播执行结果
+        waiting.forEach((resolve) => {
+          resolve(res)
+        })
+        waiting = []
+        // 后重置节流状态
+        isExecuted = true
+        if (timerExpired === true) {
+          isCalling = false
+        }
+      })
+    }
+    // oxlint-disable-next-line no-unsafe-return
+    return (await new Promise((resolve) => {
+      waiting.push(resolve)
+    })) as ReturnType<T>
+  }
+}
+
+export type FunctionThrottle<T extends AnyFunction> =
+  (...args: Parameters<T>) => Promise<ReturnType<T>>
+/**
+ * Generate a throttled function that returns a promise resolving to the result
+ * of the original function and coalesces concurrent calls.
+ *
+ * @example
+ * ```
+ * const throttled = functionThrottle(async () => "ok")
+ * const result1 = throttled()
+ * const result2 = throttled()
+ * // Expect: result1 and result2 resolve to "ok"
+ * ```
+ */
+export const functionThrottle = <T extends AnyFunction>(
+  fn: T
+): FunctionThrottle<T> => {
+  let isCalling = false
+  let waiting: AnyFunction[] = []
+  return async () => {
+    if (isCalling === false) {
+      isCalling = true
+      void Promise.resolve(fn()).then((res) => {
+        // 先广播执行结果
+        waiting.forEach((resolve) => {
+          resolve(res)
+        })
+        waiting = []
+        // 后重置节流状态
+        isCalling = false
+      })
+    }
+    // oxlint-disable-next-line no-unsafe-return
+    return (await new Promise((resolve) => {
+      waiting.push(resolve)
+    })) as ReturnType<T>
+  }
+}
+
+/**
+ * Compose functions from right to left.
+ *
+ * @example
+ * ```
+ * const addOne = (value: number) => value + 1
+ * const double = (value: number) => value * 2
+ * const composed = functionCompose(addOne, double)
+ * // Expect: 5
+ * const example1 = composed(2)
+ * ```
+ */
+export const functionCompose = <Fns extends AnyFunction[]>(
+  ...fns: Fns
+): FunctionComposeAll<Fns> => {
+  const reversedFns = fns.toReversed()
+  const initialFunction = reversedFns.shift() ?? asIs
+  const composedFunction = reversedFns.reduce((g, f) => {
+    // oxlint-disable-next-line no-explicit-any explicit-function-return-type
+    return (...args: any[]) => {
+      // oxlint-disable-next-line no-unsafe-return no-unsafe-argument
+      return f(g(...args))
+    }
+  }, initialFunction)
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  return composedFunction as FunctionComposeAll<Fns>
+}
+
+/**
+ * Pipe functions from left to right.
+ *
+ * @example
+ * ```
+ * const addOne = (value: number) => value + 1
+ * const double = (value: number) => value * 2
+ * const piped = functionPipe(addOne, double)
+ * // Expect: 6
+ * const example1 = piped(2)
+ * ```
+ */
+export const functionPipe = <Fns extends AnyFunction[]>(
+  ...fns: Fns
+): FunctionPipeAll<Fns> => {
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  return functionCompose(...fns.toReversed()) as FunctionPipeAll<Fns>
+}
+
+export type FunctionMemorized<T extends AnyFunction> =
+  (...args: Parameters<T>) => ReturnType<T>
+// oxlint-disable-next-line no-explicit-any
+const defaultMemorizeHasher = (...args: any[]): string => JSON.stringify(args)
+/**
+ * Generate a memoized function that caches results by arguments.
+ *
+ * @example
+ * ```
+ * let calls = 0
+ * const sum = (a: number, b: number) => {
+ *   calls += 1
+ *   return a + b
+ * }
+ * const memoized = functionMemorize(sum)
+ * // Expect: 3
+ * const example1 = memoized(1, 2)
+ * // Expect: 3
+ * const example2 = memoized(1, 2)
+ * // Expect: calls === 1
+ * const example3 = calls
+ * ```
+ */
+export const functionMemorize = <T extends AnyFunction>(
+  fn: T,
+  hashFunction?: (...args: Parameters<T>) => unknown
+): FunctionMemorized<T> => {
+  const cache = new Map()
+  const hasher = hashFunction ?? defaultMemorizeHasher
+  return (...args) => {
+    const key = hasher(...args)
+    if (cache.has(key)) {
+      // oxlint-disable-next-line no-unsafe-return
+      return cache.get(key)
+    }
+    // oxlint-disable-next-line no-unsafe-assignment
+    const result = fn(...args)
+    cache.set(key, result)
+    // oxlint-disable-next-line no-unsafe-return
+    return result
+  }
+}