@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/src/basic/function.ts

@@ -26,23 +26,28 @@ export const functionIife = <T extends AnyFunction>(
   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
+ * const exampleFn1 = functionOnce((x: number) => x * 2)
+ * // Expect: 10
+ * const example1 = exampleFn1(5)
+ * // Expect: 10
+ * const example2 = exampleFn1(10)
+ *
  * let callCount = 0
- * const onceFnWithSubscriber = functionOnce((x) => x * 2, (times) => { callCount = times })
- * onceFnWithSubscriber(5) // callCount is still 0
- * onceFnWithSubscriber(10) // callCount becomes 2
+ * const exampleFn2 = functionOnce((x: number) => x * 2, (times) => { callCount = times })
+ * exampleFn2(5)
+ * exampleFn2(10)
+ * // Expect: 2
+ * const example3 = callCount
  * ```
  */
 export const functionOnce = <T extends AnyFunction>(
@@ -67,27 +72,30 @@ export const functionOnce = <T extends AnyFunction>(
   }
 }
 
+/**
+ * 表示简单防抖后的函数类型。
+ */
 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)
+ * const records: number[] = []
+ * const exampleFn1 = functionDebounceSimple((x: number) => { records.push(x) }, 10)
+ * exampleFn1(5)
+ * exampleFn1(10)
+ * // Expect: records.length === 0
+ * const example1 = records.length === 0
  * ```
  */
 export const functionDebounceSimple = <T extends AnyFunction>(
   fn: T,
   ms: number
 ): FunctionDebouncedSimple<T> => {
-  let timer: NodeJS.Timeout
+  let timer: ReturnType<typeof setTimeout>
   return (...args) => {
     clearTimeout(timer)
     timer = setTimeout(() => {
@@ -96,29 +104,30 @@ export const functionDebounceSimple = <T extends AnyFunction>(
   }
 }
 
+/**
+ * 表示返回 `Promise` 的防抖函数类型。
+ */
 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.
+ * 生成一个返回 `Promise` 的防抖函数，并在防抖窗口内合并并发调用。
  *
  * @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
+ * const exampleFn1 = debounce(async (x: number) => x * 2, 10)
+ * const example1 = exampleFn1(5)
+ * const example2 = exampleFn1(10)
+ * // Expect: example1 instanceof Promise
+ * const example3 = example1 instanceof Promise
+ * // Expect: example2 instanceof Promise
+ * const example4 = example2 instanceof Promise
  * ```
  */
 export const debounce = <T extends AnyFunction>(
   fn: T,
   ms: number
 ): FunctionDebounced<T> => {
-  let timer: NodeJS.Timeout
+  let timer: ReturnType<typeof setTimeout>
   let waiting: AnyFunction[] = []
   return async (...args) => {
     clearTimeout(timer)
@@ -139,25 +148,23 @@ export const debounce = <T extends AnyFunction>(
 }
 
 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.
+ * 当 `strict` 为 `true` 时，节流窗口会同时考虑等待时长与目标函数执行时长。
  *
  * @example
  * ```
  * let called = 0
- * const throttled = functionThrottleTimeSimple(() => { called += 1 }, 100)
- * throttled()
- * throttled()
- * // Expect: called === 1
+ * const exampleFn1 = functionThrottleTimeSimple(() => { called += 1 }, 100)
+ * exampleFn1()
+ * exampleFn1()
+ * // Expect: 1
  * const example1 = called
  * ```
  */
@@ -212,19 +219,21 @@ export const functionThrottleTimeSimple = <T extends AnyFunction>(
   }
 }
 
+/**
+ * 表示执行期间丢弃重复调用的简单节流函数类型。
+ */
 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 exampleFn1 = functionThrottleSimple(() => { called += 1 })
+ * exampleFn1()
+ * exampleFn1()
+ * // Expect: 1
  * const example1 = called
  * ```
  */
@@ -256,23 +265,25 @@ export const functionThrottleSimple = <T extends AnyFunction>(
   }
 }
 
+/**
+ * 表示返回 `Promise` 的时间节流函数类型。
+ */
 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.
+ * 生成一个返回 `Promise` 的时间节流函数。
  *
- * 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.
+ * 当 `strict` 为 `true` 时，节流窗口会同时考虑等待时长与目标函数执行时长。
  *
  * @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
+ * const exampleFn1 = throttleTime(async (value: number) => value * 2, 100)
+ * const example1 = exampleFn1(2)
+ * const example2 = exampleFn1(3)
+ * // Expect: example1 instanceof Promise
+ * const example3 = example1 instanceof Promise
+ * // Expect: example2 instanceof Promise
+ * const example4 = example2 instanceof Promise
  * ```
  */
 export const throttleTime = <T extends AnyFunction>(
@@ -323,18 +334,23 @@ export const throttleTime = <T extends AnyFunction>(
   }
 }
 
+/**
+ * 表示合并并发调用的节流函数类型。
+ */
 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.
+ * 生成一个返回 `Promise` 的节流函数，并合并并发调用。
  *
  * @example
  * ```
- * const throttled = functionThrottle(async () => "ok")
- * const result1 = throttled()
- * const result2 = throttled()
- * // Expect: result1 and result2 resolve to "ok"
+ * const exampleFn1 = functionThrottle(async () => "ok")
+ * const example1 = exampleFn1()
+ * const example2 = exampleFn1()
+ * // Expect: example1 instanceof Promise
+ * const example3 = example1 instanceof Promise
+ * // Expect: example2 instanceof Promise
+ * const example4 = example2 instanceof Promise
  * ```
  */
 export const functionThrottle = <T extends AnyFunction>(
@@ -409,6 +425,9 @@ export const functionPipe = <Fns extends AnyFunction[]>(
   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
@@ -434,7 +453,7 @@ const defaultMemorizeHasher = (...args: any[]): string => JSON.stringify(args)
  */
 export const functionMemorize = <T extends AnyFunction>(
   fn: T,
-  hashFunction?: (...args: Parameters<T>) => unknown
+  hashFunction?: (...args: Parameters<T>) => unknown | undefined
 ): FunctionMemorized<T> => {
   const cache = new Map()
   const hasher = hashFunction ?? defaultMemorizeHasher

package/src/basic/index.ts

@@ -13,5 +13,6 @@ export * from "./error.ts"
 export * from "./regexp.ts"
 export * from "./promise.ts"
 export * from "./stream.ts"
+export * from "./schedule.ts"
 
 export * from "./enhance.ts"