promise

Promise 工具函数。

导入

import { 
  isPromiseLike, 
  promiseDelay, 
  promiseTimeout, 
  promiseWhen, 
  promiseShared, 
  createMinDelayPromise 
} from '@cloudcome/utils-core/promise'

函数

isPromiseLike

判断是否为类 Promise 对象。

function isPromiseLike<T>(unknown: unknown): unknown is Promise<T>

参数

参数	类型	描述
unknown	unknown	要检查的值

返回值

unknown is Promise<T> - 是否为类 Promise 对象

示例

isPromiseLike(Promise.resolve()) // true
isPromiseLike({ then: () => {} }) // true
isPromiseLike({}) // false
isPromiseLike(null) // false

promiseDelay

延迟执行。

function promiseDelay(ms?: number, ctrl?: AbortController): Promise<void>

参数

参数	类型	默认值	描述
ms	number	0	延迟时间（毫秒）
ctrl	AbortController	-	可选，用于取消延迟

返回值

Promise<void>

示例

// 基本用法
await promiseDelay(1000) // 延迟 1 秒

// 使用 AbortController 取消
const ctrl = new AbortController()
setTimeout(() => ctrl.abort(), 500) // 500ms 后取消
await promiseDelay(1000, ctrl) // 不会等待 1 秒

promiseTimeout

为 Promise 添加超时。

function promiseTimeout<T>(promise: Promise<T>, ms: number): Promise<T>

参数

参数	类型	描述
promise	Promise<T>	原始 Promise
ms	number	超时时间（毫秒）

返回值

Promise<T> - 带超时的 Promise

示例

// 基本用法
const data = await promiseTimeout(fetch('/api/data'), 5000) // 5 秒超时

// 超时会抛出错误
try {
  await promiseTimeout(promiseDelay(10000), 1000) // 1 秒超时
} catch (error) {
  console.error('Timeout!') // 会执行这里
}

promiseWhen

等待条件满足。

function promiseWhen(condition: () => boolean, ms?: number): Promise<void>

参数

参数	类型	默认值	描述
condition	() => boolean	-	条件函数
ms	number	10	检查间隔（毫秒）

返回值

Promise<void>

示例

let count = 0
const interval = setInterval(() => {
  count++
}, 100)

// 等待 count >= 5
await promiseWhen(() => count >= 5, 50)
console.log(count) // >= 5

clearInterval(interval)

promiseShared

共享 Promise，避免重复请求。

function promiseShared<T>(promise: Promise<T>): Promise<T>

参数

参数	类型	描述
promise	Promise<T>	原始 Promise

返回值

Promise<T> - 共享的 Promise

示例

let callCount = 0
const fetchData = () => {
  callCount++
  return promiseDelay(100).then(() => 'data')
}

// 多次调用共享的 Promise
const shared = promiseShared(fetchData())
const [result1, result2] = await Promise.all([shared, shared])

console.log(result1) // 'data'
console.log(result2) // 'data'
console.log(callCount) // 1，只调用了一次

createMinDelayPromise

创建最小延迟函数。

function createMinDelayPromise(ms: number): () => Promise<void>

参数

参数	类型	描述
ms	number	最小延迟时间（毫秒）

返回值

() => Promise<void> - 延迟函数

示例

const minDelay = createMinDelayPromise(500)

// 使用最小延迟
const start = Date.now()
await minDelay()
const elapsed = Date.now() - start
console.log(elapsed >= 500) // true

// 配合异步操作使用
const minDelay2 = createMinDelayPromise(1000)
async function loadData() {
  const delay = minDelay2()
  const data = await fetch('/api/data')
  await delay // 确保至少等待 1 秒
  return data
}