@composy/cache-vue

@composy/cache-vue

@composy/cache-vue 是 @composy/cache-core 的 Vue 适配层，负责：

• 原生 Vue 插件接入（createCachePlugin）
• Engine 模式接入（createCacheEnginePlugin）
• 响应式 composables（useCache、useCacheState、useCacheQuery、useSWR）
• 指令/组件/装饰器适配

English

公共 API 分层见 PUBLIC-API.md。Core 的缓存管理器、策略和存储契约请从 @composy/cache-core 引入；Vue 包不重复导出或复制 Core runtime。

安装

pnpm add @composy/cache-vue

双插件体系

1) 原生 Vue 插件

import { createCachePlugin } from '@composy/cache-vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.use(
  createCachePlugin({
    strategy: 'lru',
    maxSize: 200,
    defaultTTL: 15000,
    enablePersistence: true,
    storageType: 'localStorage',
    storagePrefix: 'cache-demo:',
  })
)

app.mount('#app')

2) Engine 适配插件

import { createCacheEnginePlugin } from '@composy/cache-vue'
import { createVueEngine } from '@composy/engine-vue'

const cachePlugin = createCacheEnginePlugin({
  maxSize: 200,
  defaultTTL: 15000,
  vue: {
    globalPropertyName: '$cache',
    registerDirective: true,
    registerComponents: true,
  },
})

const engine = createVueEngine({
  app: { rootComponent: App },
  plugins: [cachePlugin as any],
})

engine.mount('#app')

该插件同时覆盖：

• app 已可用时的立即安装
• app:created 事件后的延迟安装

Composables

useCache

useCache 优先使用注入实例（插件提供），未注入时才本地创建。

import { useCache } from '@composy/cache-vue'

const { cache, set, get, peek, stats, invalidateByTag, getKeysByTag } = useCache({
  reactiveStats: true,
})

set(
  'user:1',
  { id: 1 },
  {
    tags: ['user'],
    namespace: '用户模块',
    ttl: 5000,
  }
)

const data = get('user:1')
const raw = peek('user:1')
const taggedKeys = getKeysByTag('user')
invalidateByTag('user')

useCacheState

const { size, hitRate, isEmpty, isFull, refresh } = useCacheState({
  syncInterval: 1500,
})

useCacheQuery

基于 core 查询模块的响应式封装。

const { data, loading, isFromCache, execute, refetch } = useCacheQuery({
  key: 'api:list',
  queryFn: () => fetch('/api/list').then(r => r.json()),
  dedupe: true,
  swr: true,
  staleTime: 2000,
  ttl: 10000,
})

useSWR

const { data, isValidating, revalidate, mutate } = useSWR({
  key: 'api:user:1',
  fetcher: () => fetch('/api/user/1').then(r => r.json()),
  staleTime: 1000,
  ttl: 10000,
})

指令/组件/装饰器

v-cache

<p v-cache="{ key: 'home:title', fetcher: loadTitle, ttl: 5000 }">加载中</p>

CacheProvider

<CacheProvider :options="{ namespace: '局部命名空间' }" v-slot="{ cache }">
  <button @click="cache.set('x', 1)">写入</button>
</CacheProvider>

@Cacheable

@Cacheable({ cache, ttl: 10000, namespace: '服务层', tags: ['api'] })
async getUser(id: string) {
  return request(`/api/user/${id}`)
}

@Cacheable 由 core 提供，Vue 包仅作转出，便于在非 Vue 场景共享。

迁移说明（重构前 -> 重构后）

插件结构

• 旧：单一 plugin.ts
• 新：
  • plugins/plugin.ts（原生 Vue）
  • plugins/enginePlugin.ts（Engine 适配）
  • plugins/index.ts（聚合导出）
  • runtime/cacheAppInstaller.ts（统一 App 安装入口）
  • runtime/cacheManagerResolver.ts（统一 cache 来源解析）
  • runtime/cacheEventBinding.ts（统一事件订阅与批量刷新）

注入键

• 旧：多处重复定义
• 新：CACHE_INJECTION_KEY 单一来源（src/constants/index.ts）

useCache 行为

• 旧：默认本地创建，容易与插件实例割裂
• 新：优先注入实例，未注入才创建本地实例

useCacheQuery/useSWR

• 旧：各自重复实现查询逻辑
• 新：统一走 core 查询模块，Vue 仅做响应式包装

运行时桥接

• 旧：原生 Vue 插件、Engine 插件、Composables 各自维护安装/解析/订阅逻辑
• 新：统一复用 runtime/*，让注入、App 安装、事件刷新和实例来源保持同一套规则

构建与验证

本包使用 @composy/builder 构建，并在构建后归一化 ESM/CJS 声明文件中的相对导入，确保 NodeNext 消费者可以解析 es/、esm/ 与 lib/ 产物。

pnpm build
pnpm type-check
pnpm test:run
pnpm lint:check
pnpm consumer:check # NodeNext 声明、SSR 与真实 tarball 消费者检查

License

MIT

📝 更新日志

• CHANGELOG.md