@planet-matrix/mobius-model 0.6.0 → 0.10.1

package/src/basic/README.md

@@ -2,48 +2,53 @@
 
 ## Description
 
-Basic 模块提供面向 JavaScript 运行时值（runtime value）的通用基础能力，用于围绕基础类型、内建对象、常见容器与轻量流程控制建立稳定、可组合、低假设的公共语义。
+Basic 模块提供面向 JavaScript 运行时值（runtime value）的通用基础能力，用于承载一组稳定、可组合、低假设的便捷操作。
 
-它关注的不是某个具体业务领域，而是那些可以长期复用的值级操作：判断、转换、裁剪、组合、格式化、调度、异步组织，以及与少量宿主无关接口的桥接。
+这里所说的“运行时值”，既包括 primitive value，也包括 JavaScript 运行时原生提供的常见对象与接口，例如 `Function`、`Promise`、`ReadableStream`、`Date`、`Error`、`RegExp` 等。
+
+它关注的不是某个具体业务领域，而是围绕运行时值展开、可以长期复用的基础处理能力。
 
 ## For Understanding
 
-理解 Basic 模块时，首先要把握它的核心边界：这里承载的是“值如何被稳定处理”，而不是“宿主环境如何被接入和驱动”。只要某项能力的主要价值在于处理字符串、数字、布尔值、BigInt、符号（Symbol）、数组、对象、函数、Promise、Error、正则表达式（regular expression）、时间值、流（stream）等运行时值，它通常就有机会属于 Basic。
+理解 Basic 模块时，首先要把握它的核心边界：这里承载的是“运行时直接提供的值如何被方便、稳定地处理”，而不是“围绕某个自定义对象系统、业务模型或宿主入口建立长期语义”。只要某项能力的主要价值在于处理字符串、数字、布尔值、BigInt、符号（Symbol）、数组、对象、函数、Promise、Error、正则表达式（regular expression）、时间值、流（stream）等运行时值，它通常就有机会属于 Basic。
+
+从这个角度看，`function`、`promise`、`stream` 与 `boolean`、`string`、`object`、`array`、`number` 没有本质区别，都是运行时已经给出的基础对象形态。
 
-反过来说，如果某项能力的重点已经变成注册全局监听器、驱动宿主生命周期、读取运行时上下文、感知平台能力，或消费宿主级事件源，那么它通常就不再属于 Basic，即使它最后处理的对象仍然表现为某种值。Basic 关心的是值级语义，而不是环境级语义。
+反过来说，如果某项能力的重点已经变成注册全局监听器、读取运行时上下文、感知平台能力、消费宿主级事件源，或围绕某类自定义对象建立独立问题域，那么它通常就不再属于 Basic。Basic 关心的是运行时值的通用处理语义，而不是环境级语义、业务对象语义或更高层的领域模型语义。
 
 这也意味着 Basic 不是“随手工具箱”。一个能力只有在满足以下条件时，才适合进入这个模块：
 
-- 它表达的是稳定、清楚、可复用的值级问题域。
+- 它表达的是稳定、清楚、可复用的值级问题。
 - 它对调用方前提的假设足够少，能在不同项目中长期成立。
-- 它适合通过清楚的输入输出语义被组合，而不是依赖隐式上下文或宿主副作用。
+- 它适合通过清楚的输入输出语义被组合，而不是依赖隐式上下文、特定业务约定或某个自定义对象体系的内部状态。
 
 ## For Using
 
-当你需要把分散在业务代码中的基础判断、值转换、容器处理和轻量流程控制整理成稳定能力时，可以使用这个模块。它适合放在业务逻辑与语言原生能力之间，作为一层更可复用、也更可测试的基础模型层。
+当你需要把分散在业务代码中的基础判断、值转换、容器处理，以及围绕函数、Promise、流等运行时原生对象的便捷操作整理成稳定能力时，可以使用这个模块。它适合放在业务逻辑与语言原生能力之间，作为一层更可复用、更可测试的基础模型层。
 
 当前公共能力大致可以按以下几类理解：
 
-- 值判断与基础守卫：例如 primitive、对象、数组、空值、数字特征等运行时判断，用于减少重复的分支代码。
+- 值判断与基础守卫：例如 primitive、对象、数组、空值、数字特征等运行时判断，用于减少重复分支。
 - 基础值处理：例如字符串、数字、布尔值、BigInt、符号等常见值类型的转换、裁剪、计算与格式化。
 - 容器处理：例如数组与对象的筛选、映射、分区、裁剪、合并、字段选择与标准化，适合在进入业务模型前先整理数据形态。
-- 函数与流程控制：例如一次性调用、防抖、节流、组合、管道、记忆化、条件执行等轻量控制能力。
+- 函数相关：例如一次性调用、防抖、节流、组合、管道、记忆化、条件执行等围绕函数值展开的便捷能力。
 - 异步与流处理：例如 Promise 队列、重试、轮询、失败结果表达，以及围绕 `ReadableStream` 的基础消费与转换。
 - 时间、错误与正则辅助：例如时间格式化、异常字符串化、常见模式判断等值级辅助能力。
 - 显式增强能力：如果某个能力会对内建对象做增强，它必须保持显式调用、行为可审查，并且不应成为其它公共能力成立的隐含前提。
 
-如果你的问题已经需要环境感知、平台能力探测、全局异常监听或更明确的领域语义，应优先考虑 Environment、Exception 或其它更贴近问题域的模块，而不是继续把能力堆进 Basic。
+如果你的问题已经需要环境感知、平台能力探测、全局异常监听，或需要围绕某类自定义对象建立独立问题域，应优先考虑 Environment、Exception 或其它更贴近问题域的模块，而不是继续把能力堆进 Basic。
 
 ## For Contributing
 
-贡献 Basic 模块时，首要任务不是补齐一个方便函数，而是确认这项能力是否真的表达了稳定的值级语义。这里应长期承载的是对运行时值的清楚建模，而不是对某个调用点临时痛点的修补。
+贡献 Basic 模块时，首要任务不是补齐一个方便函数，而是确认这项能力是否真的表达了稳定、可复用的运行时基础语义。这里应长期承载的是对运行时值的清楚整理，而不是对某个调用点的临时修补。
 
 在扩展时，应优先遵守以下模块边界：
 
-- 只收纳围绕运行时值本身展开的判断、转换、组合、格式化与轻量流程控制。
+- 只收纳围绕运行时值展开的判断、转换、组合、格式化与其它稳定便捷操作。
 - 不把环境探测、宿主监听、全局状态操纵或平台接入逻辑放入 Basic。
-- 不为了省几行调用代码而公开一次性便捷包装；只有值得长期承诺的公共语义才应进入模块。
+- 不为了省几行调用代码就公开一次性便捷包装；只有值得长期承诺的公共语义才应进入模块。
 - 如果某项能力依赖显式增强内建对象，必须让增强保持可选，而不是让整个模块隐式建立在原型修改之上。
+- 若新增能力主要是在围绕某类自定义对象、某套业务状态机、某个框架生命周期或某个宿主入口建立独立问题域，那么它通常应进入更贴近该问题域的模块，而不是留在 Basic。
 
 ### JSDoc 注释格式要求
 
@@ -74,14 +79,14 @@ Basic 模块提供面向 JavaScript 运行时值（runtime value）的通用基
 - 子模块不需要有自己的 `README.md`。
 - 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
 - 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
-- Basic 的实现应优先保证输入输出语义直接、低副作用、可组合，而不是追求隐式魔法或宿主绑定行为。
+- Basic 的实现应优先保证输入输出语义直接、低副作用、可组合，而不是追求隐式魔法、业务耦合或依赖特定框架约定的包装。
 
 ### 导出策略要求
 
 - 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
 - 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
 - Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
-- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的值级语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的运行时基础语义，而不是某段实现细节、业务约定或一次性便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
 
 ### 测试要求
 

package/src/basic/error.ts

@@ -39,13 +39,27 @@ export const errorIsNetworkError = (error: unknown): error is Error => {
 }
 
 /**
- * Stringifies an exception into a readable format.
+ * Stringifies an error into a readable format.
  */
-export const errorStringifyException = (exception: unknown): string => {
-  if (isError(exception)) {
-    return `${exception.name}: ${exception.message}`
+export const errorStringify = (error: unknown): string => {
+  if (isError(error)) {
+    return `${error.name}: ${error.message}`
   }
   else {
-    return `${String(exception)}`
+    return `${String(error)}`
+  }
+}
+
+/**
+ * Converts a value to an Error object. If the value is already an Error,
+ * it is returned as is. Otherwise, a new Error is created with the
+ * stringified value as its message.
+ */
+export const toError = (value: unknown): Error => {
+  if (isError(value)) {
+    return value
+  }
+  else {
+    return new Error(String(value))
   }
 }

package/src/basic/function.ts

@@ -95,7 +95,7 @@ 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(() => {
@@ -127,7 +127,7 @@ 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)

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"

package/src/basic/promise.ts

@@ -6,16 +6,16 @@ import { isPlainObject } from "./is.ts"
  * @example
  * ```
  * // Expect: 6
- * const example1 = await promiseThen((value: number) => value * 2, Promise.resolve(3))
+ * const example1 = await promiseThen(Promise.resolve(3), (value: number) => value * 2)
  * // Expect: "ok!"
- * const example2 = await promiseThen((value: string) => `${value}!`, Promise.resolve("ok"))
+ * const example2 = await promiseThen(Promise.resolve("ok"), (value: string) => `${value}!`)
  * ```
  */
 export const promiseThen = async <V, R>(
-  doSomething: (value: V) => R | PromiseLike<R>,
   target: Promise<V>,
+  doSomething: (value: V) => R | PromiseLike<R>,
 ): Promise<R> => {
-  return await target.then(doSomething)
+  return await target.then((value) => doSomething(value))
 }
 
 /**
@@ -24,16 +24,16 @@ export const promiseThen = async <V, R>(
  * @example
  * ```
  * // Expect: "fallback"
- * const example1 = await promiseCatch(() => "fallback", Promise.reject(new Error("x")))
+ * const example1 = await promiseCatch(Promise.reject(new Error("x")), () => "fallback")
  * // Expect: 3
- * const example2 = await promiseCatch(() => 0, Promise.resolve(3))
+ * const example2 = await promiseCatch(Promise.resolve(3), () => 0)
  * ```
  */
 export const promiseCatch = async <V, R>(
-  doSomething: (reason: unknown) => R | PromiseLike<R>,
   target: Promise<V>,
+  doSomething: (reason: unknown) => R | PromiseLike<R>,
 ): Promise<V | R> => {
-  return await target.catch(doSomething)
+  return await target.catch((reason: unknown) => doSomething(reason))
 }
 
 /**
@@ -43,25 +43,54 @@ export const promiseCatch = async <V, R>(
  * ```
  * let cleaned = false
  * // Expect: 10
- * const example1 = await promiseFinally(() => { cleaned = true }, Promise.resolve(10))
+ * const example1 = await promiseFinally(Promise.resolve(10), () => { cleaned = true })
  * // Expect: true
  * const example2 = cleaned
  * ```
  */
 export const promiseFinally = async <V>(
-  doSomething: () => void,
   target: Promise<V>,
+  doSomething: () => void,
 ): Promise<V> => {
-  return await target.finally(doSomething)
+  return await target.finally(() => doSomething())
+}
+
+export interface PromiseDeferred<V> {
+  promise: Promise<V>
+  resolve: (value: V) => void
+  reject: (reason: unknown) => void
+}
+/**
+ * Create a deferred promise with external resolve and reject functions.
+ *
+ * @example
+ * ```
+ * const deferred = promiseDeferred<number>()
+ * // Expect: typeof deferred.resolve === "function"
+ * const example1 = typeof deferred.resolve
+ * deferred.resolve(42)
+ * const example2 = await deferred.promise
+ * // Expect: 42
+ * ```
+ */
+export const promiseDeferred = <V>(): PromiseDeferred<V> => {
+  let externalResolve!: (value: V) => void
+  let externalReject!: (reason: unknown) => void
+  const promise = new Promise<V>((resolve, reject) => {
+    externalResolve = resolve
+    externalReject = reject
+  })
+  return { promise, resolve: externalResolve, reject: externalReject }
 }
 
-const INTERNAL_PROMISE_FAIL_RESULT_TYPE: symbol = Symbol("fail")
+const INTERNAL_PROMISE_FAIL_RESULT_TYPE: unique symbol = Symbol("fail")
+type InternalPromiseFailResultType = typeof INTERNAL_PROMISE_FAIL_RESULT_TYPE
 
 /**
  * 表示标准化的 Promise 失败结果。
  */
 export interface PromiseFailResult {
-  __type__: typeof INTERNAL_PROMISE_FAIL_RESULT_TYPE
+  __type__: InternalPromiseFailResultType
   reason: unknown
 }
 
@@ -75,14 +104,23 @@ export interface PromiseIndexedFailResult extends PromiseFailResult {
 /**
  * 根据拒因构造标准化的 Promise 失败结果。
  */
-export const promiseConstructFailResult = (reason: unknown): PromiseFailResult => {
+export const promiseCreateFailResult = (reason: unknown): PromiseFailResult => {
   return { __type__: INTERNAL_PROMISE_FAIL_RESULT_TYPE, reason }
 }
 /**
  * 判断目标值是否为标准化的 Promise 失败结果。
  */
-export const isPromiseFailResult = (target: unknown): target is PromiseFailResult => {
-  return isPlainObject(target) && target["__type__"] === INTERNAL_PROMISE_FAIL_RESULT_TYPE
+export const promiseIsFailResult = (target: unknown): target is PromiseFailResult => {
+  if (isPlainObject(target) === false) {
+    return false
+  }
+  if ("__type__" in target === false) {
+    return false
+  }
+  if (target["__type__"] !== INTERNAL_PROMISE_FAIL_RESULT_TYPE) {
+    return false
+  }
+  return true
 }
 /**
  * 用作 `Promise.catch` 的 `onrejected` 回调，并返回标准化失败结果。
@@ -98,9 +136,8 @@ export const promiseFilterSuccessResults = <V>(
   results: Array<V | PromiseFailResult>,
 ): V[] => {
   const filtered = results.filter(result => {
-    return isPromiseFailResult(result) === false
+    return promiseIsFailResult(result) === false
   })
-  // oxlint-disable-next-line no-unsafe-type-assertion
   return filtered as V[]
 }
 /**
@@ -112,7 +149,7 @@ export const promiseFilterFailResults = <V>(
   const filtered = results.reduce<PromiseIndexedFailResult[]>((
     accumulatedResults, currentResult, index
   ) => {
-    if (isPromiseFailResult(currentResult)) {
+    if (promiseIsFailResult(currentResult)) {
       accumulatedResults.push({ ...currentResult, index })
     }
     return accumulatedResults
@@ -131,8 +168,10 @@ interface PromiseQueueRestPromiseMakerContext<V, S = unknown> {
   previousResult: V | PromiseFailResult
   state: S
 }
-type PromiseQueueFirstPromiseMaker<T, S = unknown> = (context: PromiseQueueFirstPromiseMakerContext<S>) => Promise<T>
-type PromiseQueueRestPromiseMaker<T, S = unknown> = (context: PromiseQueueRestPromiseMakerContext<T, S>) => Promise<T>
+type PromiseQueueFirstPromiseMaker<T, S = unknown>
+  = (context: PromiseQueueFirstPromiseMakerContext<S>) => Promise<T>
+type PromiseQueueRestPromiseMaker<T, S = unknown>
+  = (context: PromiseQueueRestPromiseMakerContext<T, S>) => Promise<T>
 type PromiseQueuePromiseMakers<T, S = unknown> = [
   PromiseQueueFirstPromiseMaker<T, S>,
   ...Array<PromiseQueueRestPromiseMaker<T, S>>
@@ -155,7 +194,7 @@ export interface PromiseQueueOptions {
  * // Expect: [1, 2]
  * const example1 = await promiseQueue<number>([
  *   async () => 1,
- *   async ({ previousResult }) => (isPromiseFailResult(previousResult) ? 0 : previousResult + 1),
+ *   async ({ previousResult }) => (promiseIsFailResult(previousResult) ? 0 : previousResult + 1),
  * ])
  * ```
  */
@@ -169,7 +208,6 @@ export const promiseQueue = async <T, S = unknown>(
   let context: PromiseQueueFirstPromiseMakerContext<S> | PromiseQueueRestPromiseMakerContext<T, S> = {
     index: 0,
     hasPreviousResult: false,
-    // oxlint-disable-next-line no-unsafe-type-assertion
     state: undefined as unknown as S
   }
 
@@ -205,18 +243,20 @@ export const promiseQueue = async <T, S = unknown>(
 }
 
 interface PromiseRetryFirstPromiseMakerContext<S = unknown> {
-  time: number
+  index: number
   hasPreviousResult: false
   state: S
 }
 interface PromiseRetryRestPromiseMakerContext<T, S = unknown> {
-  time: number
+  index: number
   hasPreviousResult: true
   previousResult: T | PromiseFailResult
   state: S
 }
 type PromiseRetryPromiseMaker<T, S = unknown> = (
-  context: PromiseRetryFirstPromiseMakerContext<S> | PromiseRetryRestPromiseMakerContext<T, S>
+  context:
+    | PromiseRetryFirstPromiseMakerContext<S>
+    | PromiseRetryRestPromiseMakerContext<T, S>
 ) => Promise<T>
 
 /**
@@ -228,9 +268,10 @@ export interface PromiseRetryOptions {
    */
   breakTime?: number
   /**
+   * `0` 表示仅执行首次尝试，不进行额外重试。
    * @default Infinity
    */
-  maxTryTimes?: number
+  maxTryIndex?: number | undefined
 }
 /**
  * Retry while the predicate indicates the result is not acceptable.
@@ -257,34 +298,33 @@ export const promiseRetryWhile = async <T, S = unknown>(
 ): Promise<T | PromiseFailResult> => {
   const {
     breakTime = 0,
-    maxTryTimes = Infinity,
+    maxTryIndex = Infinity,
   } = options ?? {}
 
-  if (maxTryTimes < 1) {
-    throw new Error("`maxTryTimes` must be greater than 0.")
+  if (maxTryIndex < 0) {
+    throw new Error("`maxTryIndex` must be greater than or equal to 0.")
   }
 
-  let time = 1
+  let index = 0
   // oxlint-disable-next-line no-accumulating-spread
   let context: PromiseRetryFirstPromiseMakerContext<S> | PromiseRetryRestPromiseMakerContext<T, S> = {
-    time,
+    index,
     hasPreviousResult: false,
-    // oxlint-disable-next-line no-unsafe-type-assertion
     state: undefined as unknown as S
   }
   let result = await promiseMaker(context).catch(promiseCatchToFailResult)
 
   while (
-    (isPromiseFailResult(result) || (await predicate(result)))
-    && time < maxTryTimes
+    (promiseIsFailResult(result) || (await predicate(result)))
+    && index < maxTryIndex
   ) {
-    time = time + 1
+    index = index + 1
     // oxlint-disable-next-line no-loop-func
     result = await new Promise<T | PromiseFailResult>((resolve) => {
       setTimeout(() => {
         context = {
           ...context,
-          time,
+          index,
           hasPreviousResult: true,
           previousResult: result,
         }
@@ -315,40 +355,39 @@ export const promiseRetryWhile = async <T, S = unknown>(
  * @see {@link promiseRetryWhile}
  */
 export const promiseRetryUntil = async <T, S = unknown>(
-  predicate: (value: T, time: number) => boolean | Promise<boolean>,
+  predicate: (value: T, index: number) => boolean | Promise<boolean>,
   promiseMaker: PromiseRetryPromiseMaker<T, S>,
   options?: PromiseRetryOptions | undefined,
 ): Promise<T | PromiseFailResult> => {
   const {
     breakTime = 0,
-    maxTryTimes = Infinity,
+    maxTryIndex = Infinity,
   } = options ?? {}
 
-  if (maxTryTimes < 1) {
-    throw new Error("`maxTryTimes` must be greater than 0.")
+  if (maxTryIndex < 0) {
+    throw new Error("`maxTryIndex` must be greater than or equal to 0.")
   }
 
-  let time = 1
+  let index = 0
   // oxlint-disable-next-line no-accumulating-spread
   let context: PromiseRetryFirstPromiseMakerContext<S> | PromiseRetryRestPromiseMakerContext<T, S> = {
-    time,
+    index,
     hasPreviousResult: false,
-    // oxlint-disable-next-line no-unsafe-type-assertion
     state: undefined as unknown as S
   }
   let result = await promiseMaker(context).catch(promiseCatchToFailResult)
 
   while (
-    (isPromiseFailResult(result) || !(await predicate(result, time)))
-    && time < maxTryTimes
+    (promiseIsFailResult(result) || !(await predicate(result, index)))
+    && index < maxTryIndex
   ) {
-    time = time + 1
+    index = index + 1
     // oxlint-disable-next-line no-loop-func
     result = await new Promise<T | PromiseFailResult>((resolve) => {
       setTimeout(() => {
         context = {
           ...context,
-          time,
+          index,
           hasPreviousResult: true,
           previousResult: result
         }
@@ -362,13 +401,14 @@ export const promiseRetryUntil = async <T, S = unknown>(
 
 /**
  * Start periodic asynchronous execution and return a function to stop it.
+ * Rejected runs are logged and ignored to avoid unhandled promise rejections.
  *
  * @example
  * ```
  * const records: number[] = []
- * const stop = promiseInterval(10, async (time) => {
- *   records.push(time)
- *   return time
+ * const stop = promiseInterval(10, async (index) => {
+ *   records.push(index)
+ *   return index
  * })
  * // Later: stop()
  * // Expect: typeof stop === "function"
@@ -377,13 +417,15 @@ export const promiseRetryUntil = async <T, S = unknown>(
  */
 export const promiseInterval = <T>(
   interval: number,
-  promiseMaker: (time: number) => Promise<T>,
+  promiseMaker: (index: number) => Promise<T>,
 ): (() => void) => {
-  let time = 1
+  let index = 0
 
   const intervalID = setInterval(() => {
-    void promiseMaker(time)
-    time = time + 1
+    void promiseMaker(index).catch((error: unknown) => {
+      console.error("[promiseInterval] unexpected error occurred:", error)
+    })
+    index = index + 1
   }, interval)
 
   return () => {
@@ -392,18 +434,20 @@ export const promiseInterval = <T>(
 }
 
 interface PromiseForeverFirstPromiseMakerContext<S = unknown> {
-  time: number
+  index: number
   hasPreviousResult: false
   state: S
 }
 interface PromiseForeverRestPromiseMakerContext<T, S = unknown> {
-  time: number
+  index: number
   hasPreviousResult: true
   previousResult: T | PromiseFailResult
   state: S
 }
 type PromiseForeverPromiseMaker<T, S = unknown> = (
-  context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S>
+  context:
+    | PromiseForeverFirstPromiseMakerContext<S>
+    | PromiseForeverRestPromiseMakerContext<T, S>
 ) => Promise<T>
 
 /**
@@ -414,60 +458,80 @@ export interface PromiseForeverOptions {
    * @default 0
    */
   breakTime?: number | undefined
-  onRejected?: ((time: number, result: PromiseFailResult) => void) | undefined
+  onRejected?: ((index: number, result: PromiseFailResult) => void) | undefined
+}
+export interface PromiseForeverResult {
+  index: number
+  isStopped: boolean
+  stop: () => void
 }
 /**
  * Continuously execute an async maker forever with optional delay and rejection hook.
  *
+ * - 至少会执行一次，`stop()` 可以用来提前停止后续执行。
+ * - `index` 从 `0` 开始，表示当前执行轮次。
+ * - 如果某一轮结束后已经排入了下一轮的定时器，调用 `stop()` 不会取消那一轮；
+ *   它只会阻止后续继续排入新的轮次。
+ *
  * @example
  * ```
  * let times = 0
- * promiseForever(async () => {
+ * const controller = promiseForever(async () => {
  *   times = times + 1
  *   return times
  * }, { breakTime: 0 })
- * // Expect: no return value
- * const example1 = promiseForever(async () => 1)
+ * controller.stop()
+ * // Expect: typeof controller.stop === "function"
+ * const example1 = typeof controller.stop
  * ```
  */
 export const promiseForever = <T, S = unknown>(
   promiseMaker: PromiseForeverPromiseMaker<T, S>,
   options?: PromiseForeverOptions | undefined,
-): void => {
+): PromiseForeverResult => {
   const {
     breakTime = 0,
     onRejected,
   } = options ?? {}
 
-  let time = 1
+  let index = 0
   let context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S> = {
-    time,
+    index,
     hasPreviousResult: false,
-    // oxlint-disable-next-line no-unsafe-type-assertion
     state: undefined as unknown as S
   }
+  const foreverResult: PromiseForeverResult = {
+    index,
+    isStopped: false,
+    stop: () => {
+      foreverResult.isStopped = true
+    }
+  }
 
   const handlePromise = (result: T | PromiseFailResult): void => {
-    time = time + 1
     setTimeout(() => {
+      index = index + 1
       context = {
         ...context,
-        time,
+        index,
         hasPreviousResult: true,
         previousResult: result
       }
+      foreverResult.index = index
       runPromise(context)
     }, breakTime)
   }
   const runPromise = (
-    context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S>
+    context:
+      | PromiseForeverFirstPromiseMakerContext<S>
+      | PromiseForeverRestPromiseMakerContext<T, S>
   ): void => {
     void promiseMaker(context)
       .catch((error: unknown) => {
         const failedResult = promiseCatchToFailResult(error)
         if (onRejected !== undefined) {
           try {
-            onRejected(time, failedResult)
+            onRejected(index, failedResult)
           }
           catch {
             // omit exceptions from execution of `onRejected`
@@ -478,8 +542,14 @@ export const promiseForever = <T, S = unknown>(
         }
         return failedResult
       })
-      .then(result => handlePromise(result))
+      .then(result => {
+        if (foreverResult.isStopped === false) {
+          handlePromise(result)
+        }
+      })
   }
 
   runPromise(context)
+
+  return foreverResult
 }