@composy/queue-vue

@composy/queue-vue

Runtime ownership

Native createQueuePlugin() owns the runtime it creates and destroys it after the original Vue app.unmount() completes. Engine-created runtimes are borrowed by the Vue App and remain owned by the Engine; caller-provided runtimes remain caller-owned. Repeated Engine installation is idempotent and a later App can be bound safely.

installQueueRuntime(app, runtime) 默认兼容原生插件语义并由 App 负责销毁；接入外部共享 runtime 时传入 { owned: false }，卸载 App 只解除绑定，不会销毁调用方资源。

@composy/queue-vue 是 @composy/queue-core 的 Vue 3 适配包。它不实现队列算法，只复用 core 的 TaskQueue、QueueRegistry、createQueueRuntime() 和 engine plugin。

能力范围

• createQueuePlugin()：原生 Vue plugin，向应用注入 QueueRuntime。
• useQueueRuntime()：从当前组件上下文读取共享 runtime。
• useQueue()：绑定已有 TaskQueue、创建本地队列，或通过名称复用共享队列。
• useBatchTask()：为批量任务创建一次性本地队列，并提供响应式进度、结果和错误集合。
• createQueueEnginePlugin()：在 Vue engine 场景中复用同一套 queue runtime，并同步安装到 Vue app。

安装

pnpm add @composy/queue-core @composy/queue-vue vue

原生 Vue plugin

import { createQueuePlugin } from '@composy/queue-vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)
app.use(
  createQueuePlugin({
    globalProperties: true,
  })
)
app.mount('#app')

安装后可通过以下方式访问同一 runtime：

• inject(QUEUE_RUNTIME_SYMBOL)
• useQueueRuntime()
• app.config.globalProperties.$queueRuntime
• app.config.globalProperties.$queueRegistry
• app.config.globalProperties.$queues

共享队列 composable

import { useQueue } from '@composy/queue-vue'

const requests = useQueue(
  'requests',
  async (url: string, context) => {
    const response = await fetch(url, { signal: context.signal })
    return response.json() as Promise<Record<string, unknown>>
  },
  {
    concurrency: 2,
    retries: 1,
  }
)

await requests.add('/api/users')

useQueue(name, executor, options) 会调用共享 runtime 的 ensureQueue()，同名队列会被复用，不会重复创建。

本地队列 composable

import { useQueue } from '@composy/queue-vue'

const queue = useQueue(async (file: File, context) => uploadFile(file, context.signal), {
  concurrency: 3,
})

await queue.waitForIdle()

这种形式会在组件卸载时销毁本地 TaskQueue，适合只属于当前组件的短生命周期任务。

批量任务

import { useBatchTask } from '@composy/queue-vue'

const batch = useBatchTask(['a', 'b', 'c'], async (value: string) => value.toUpperCase(), {
  concurrency: 2,
})

await batch.start()

响应式状态：

• progress
• results
• errors
• isRunning
• isPaused
• doneCount
• totalCount
• successCount
• failedCount

Engine plugin

import { createVueEngine } from '@composy/engine-vue'
import { createQueueEnginePlugin } from '@composy/queue-vue/plugins'
import App from './App.vue'

const engine = createVueEngine({
  app: { rootComponent: App },
})

await engine.use(
  createQueueEnginePlugin({
    globalProperties: true,
  })
)
await engine.mount('#app')

Vue 版 engine plugin 会优先复用：

• 调用方传入的 runtime
• Vue app 上已经安装的 queue runtime
• 新建的 Vue queue runtime

然后把该 runtime 交给 core engine plugin，保证 engine state、engine api、Vue app 注入使用同一实例。

构建产物

@composy/queue-vue 使用 @composy/builder，构建后应包含：

• dist/index.js
• dist/index.min.js
• es/**
• esm/**
• lib/**
• lib/package.json

维护约定

• 不在 Vue 侧复制 TaskQueue 的调度、重试、依赖、持久化逻辑。
• Vue 侧新增能力优先表现为 lifecycle、provide/inject、响应式状态或 plugin 适配。
• 公开类型尽量复用 @composy/queue-core 的类型，避免适配层类型漂移。