@composy/store-core 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 (2026-06-11)
+
+- 初始版本发布

package/README.md

@@ -0,0 +1,172 @@
+# @composy/store-core
+
+> 🎯 框架无关的状态管理核心库 — Store、中间件、插件、PubSub、工具函数，一应俱全
+
+[![npm version](https://img.shields.io/npm/v/@composy/store-core.svg)](https://www.npmjs.com/package/@composy/store-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ 特性
+
+- 🏗️ **Store 抽象** — BaseStore 基类 + createStore 工厂函数，灵活创建状态管理
+- 🔧 **中间件系统** — Logger/持久化/时间旅行/校验中间件开箱即用
+- 🔌 **插件扩展** — defineStorePlugin + createPluginManager，可扩展架构
+- 📢 **事件通信** — PubSub 发布订阅 + EventBus 事件总线
+- ⚡ **性能优化** — 批量更新（batch）、记忆化选择器、智能缓存
+- 🧰 **工具函数** — deepClone/deepMerge/createSelector/debounce/throttle 全套
+- 🧩 **Engine Bridge** — 框架无关的 engine state/API/container/events 生命周期桥接
+- 📦 **TypeScript** — 完整类型定义
+
+## 🧭 Core-first 边界
+
+`@composy/store-core` 是唯一的通用能力承载层。Store 生命周期、action 订阅、批处理、中间件链、时间旅行快照、engine state/API 同步和工具函数都在这里维护。
+
+框架适配包只能通过公开 API 复用 core：
+
+- Vue/Pinia runtime 由 `@composy/store-vue` 创建。
+- engine state/API/container/events 的绑定由 `createStoreEngineBridge()` 统一完成。
+- 后续新增 React/Lit/Vanilla 适配时应复用同一个 bridge，不要再复制 engine plugin 生命周期。
+
+## 📦 安装
+
+```bash
+pnpm add @composy/store-core
+```
+
+## 🚀 快速开始
+
+### createStore — 工厂函数
+
+```typescript
+import { createStore } from '@composy/store-core'
+
+const useCounterStore = createStore({
+  id: 'counter',
+  state: () => ({ count: 0 }),
+  getters: {
+    doubleCount: (state) => state.count * 2,
+    isPositive: (state) => state.count > 0,
+  },
+  actions: {
+    increment() { this.$patch({ count: this.$state.count + 1 }) },
+    decrement() { this.$patch({ count: this.$state.count - 1 }) },
+    reset() { this.$reset() },
+  },
+})
+
+const store = useCounterStore()
+store.actions.increment()
+console.info(store.$state.count)       // 1
+console.info(store.getters.doubleCount) // 2
+```
+
+### 中间件
+
+```typescript
+import {
+  createLoggerMiddleware,
+  createMiddlewareManager,
+  createPersistMiddleware,
+  createTimeTravelMiddleware,
+} from '@composy/store-core'
+
+const manager = createMiddlewareManager()
+
+// Logger — 自动记录状态变化
+manager.use(createLoggerMiddleware({ logState: true }))
+
+// 持久化 — 状态自动保存到 localStorage
+manager.use(createPersistMiddleware({ storage: 'localStorage', stores: ['user'] }))
+
+// 时间旅行 — 撤销/重做
+const { middleware, controller } = createTimeTravelMiddleware({ maxHistory: 50 })
+manager.use(middleware)
+
+controller.undo() // 撤销
+controller.redo() // 重做
+```
+
+### Engine Bridge
+
+```typescript
+import { createStoreEngineBridge } from '@composy/store-core/engine'
+
+const bridge = createStoreEngineBridge({
+  name: 'store',
+  version: '1.0.0',
+  createRuntime: () => runtime,
+})
+
+await bridge.install(engine)
+```
+
+Bridge 会同步写入 `store:runtime`、`store:pinia`、`store:api`、`store:registry` 和 `store:bus`，并注册 engine API。
+
+### PubSub & EventBus
+
+```typescript
+import { createEventBus, createPubSubWithValue } from '@composy/store-core'
+
+// PubSub — 值订阅
+const counter = createPubSubWithValue(0)
+counter.subscribe((value, oldValue) => {
+  console.info(`${oldValue} → ${value}`)
+})
+counter.setValue(42)
+
+// EventBus — 事件总线
+const bus = createEventBus()
+bus.on('state:changed', (data) => console.info(data))
+bus.emit('state:changed', { storeId: 'counter', state: { count: 1 } })
+```
+
+### 工具函数
+
+```typescript
+import {
+  createSelector, debounce, deepClone,
+  deepEqual, deepMerge,
+  getByPath, setByPath, throttle,
+} from '@composy/store-core'
+
+deepClone({ nested: { value: 1 } })           // 深拷贝
+deepMerge({ a: 1 }, { b: 2 }, { a: 3 })      // → { a: 3, b: 2 }
+deepEqual({ a: 1 }, { a: 1 })                 // → true
+createSelector((state: { count: number }) => state.count)
+getByPath(obj, 'a.b.c')                       // 路径读取
+setByPath(obj, 'a.b.c', 'new')                // 路径设置
+debounce(fn, 300)                              // 防抖
+throttle(fn, 300)                              // 节流
+```
+
+## 📚 API 速查
+
+| 模块   | API                             | 说明         |
+| ------ | ------------------------------- | ------------ |
+| 核心   | `BaseStore`                     | Store 基类   |
+| 核心   | `createStore`                   | 工厂函数     |
+| 核心   | `batch`                         | 批量更新     |
+| 中间件 | `createLoggerMiddleware`        | 日志中间件   |
+| 中间件 | `createPersistMiddleware`       | 持久化中间件 |
+| 中间件 | `createTimeTravelMiddleware`    | 时间旅行     |
+| Engine | `createStoreEngineBridge`       | engine 桥接  |
+| 插件   | `defineStorePlugin`             | 定义插件     |
+| 插件   | `createPluginManager`           | 插件管理器   |
+| 工具   | `deepClone/deepMerge/deepEqual` | 深度操作     |
+| 工具   | `getByPath/setByPath`           | 路径操作     |
+| 工具   | `createSelector`                | 记忆化选择器 |
+| 工具   | `debounce/throttle`             | 防抖/节流    |
+
+## ✅ 验证与产物
+
+```bash
+pnpm -C packages/store/packages/core run lint:check
+pnpm -C packages/store/packages/core run type-check
+pnpm -C packages/store/packages/core run test:run
+pnpm -C packages/store/packages/core run build
+```
+
+完整构建后必须同时存在 `dist`、`es`、`esm`、`lib` 四类产物目录。
+
+## 📄 License
+
+MIT © [LDesign Team](https://github.com/ldesign)