fox-mini-x 1.0.0

package/README.md

@@ -0,0 +1,202 @@
+# fox-mini-x
+
+[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)
+[![Release](https://github.com/OWNER/REPO/actions/workflows/release.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/release.yml)
+[![npm version](https://img.shields.io/npm/v/fox-mini-x.svg)](https://www.npmjs.com/package/fox-mini-x)
+
+一个用 JavaScript 实现的轻量风格状态管理库，支持 `state/getters/mutations/actions/modules`、命名空间、插件、严格模式、辅助映射函数与动态模块。
+
+## 功能特性
+
+- `createStore`：创建全局状态仓库
+- `commit / dispatch`：同步 mutation 与异步 action
+- `getters`：派生状态
+- `modules` + `namespaced`
+- 插件系统：`subscribe`、`subscribeAction(before/after/error)`
+- 严格模式：禁止在 mutation 外修改状态
+- 动态模块：`registerModule / unregisterModule / hasModule / hotUpdate`
+- 辅助函数：`mapState / mapGetters / mapMutations / mapActions`
+- `createNamespacedHelpers`
+
+## 安装
+
+```bash
+npm install fox-mini-x
+```
+
+## 快速开始
+
+```js
+import { createStore } from "fox-mini-x";
+
+const store = createStore({
+  strict: true,
+  state: () => ({ count: 0 }),
+  getters: {
+    doubleCount: (state) => state.count * 2,
+  },
+  mutations: {
+    increment(state, payload = 1) {
+      state.count += payload;
+    },
+  },
+  actions: {
+    async incrementAsync({ commit }, payload = 1) {
+      await Promise.resolve();
+      commit("increment", payload);
+    },
+  },
+});
+
+store.commit("increment", 2);
+await store.dispatch("incrementAsync", 3);
+console.log(store.state.count); // 5
+console.log(store.getters.doubleCount); // 10
+```
+
+## API 文档
+
+### `createStore(options)`
+
+创建 store 实例。
+
+主要 options：
+
+- `state`: `object | () => object`
+- `getters`: `Record<string, fn>`
+- `mutations`: `Record<string, fn>`
+- `actions`: `Record<string, fn | { root?: boolean, handler: fn }>`
+- `modules`: `Record<string, module>`
+- `plugins`: `((store) => void)[]`
+- `strict`: `boolean`
+
+### `store` 实例 API
+
+- `store.state`
+- `store.getters`
+- `store.commit(type, payload?)`
+- `store.dispatch(type, payload?)`
+- `store.subscribe((mutation, state) => void)`
+- `store.subscribeAction(fn | { before, after, error })`
+- `store.replaceState(newState)`
+- `store.registerModule(path, module, options?)`
+- `store.unregisterModule(path)`
+- `store.hasModule(path)`
+- `store.hotUpdate(newOptions)`
+
+### `createLogger(options?)`
+
+创建调试插件，记录 mutation/action：
+
+- action 生命周期日志：`before / after / error`
+- 可配置：
+  - `logActions`（默认 `true`）
+  - `logMutations`（默认 `true`）
+  - `logger`（默认 `console`）
+
+### 映射辅助函数
+
+- `mapState`
+- `mapGetters`
+- `mapMutations`
+- `mapActions`
+
+支持两种调用方式：
+
+```js
+mapState(["count"]);
+mapState("user", ["name"]);
+```
+
+### `createNamespacedHelpers(namespace)`
+
+返回绑定命名空间的辅助函数：
+
+```js
+import { createNamespacedHelpers } from "fox-mini-x";
+
+const { mapState, mapGetters, mapMutations, mapActions } =
+  createNamespacedHelpers("user");
+```
+
+## 模块与命名空间示例
+
+```js
+const store = createStore({
+  modules: {
+    user: {
+      namespaced: true,
+      state: () => ({ name: "Guest" }),
+      mutations: {
+        setName(state, name) {
+          state.name = name;
+        },
+      },
+      actions: {
+        async setNameAsync({ commit }, name) {
+          await Promise.resolve();
+          commit("setName", name);
+        },
+      },
+      getters: {
+        displayName: (state) => `@${state.name}`,
+      },
+    },
+  },
+});
+
+store.commit("user/setName", "Alice");
+console.log(store.getters["user/displayName"]); // @Alice
+```
+
+## 插件与 action 生命周期示例
+
+```js
+const tracker = (store) => {
+  store.subscribeAction({
+    before: (action) => console.log("before:", action.type),
+    after: (action) => console.log("after:", action.type),
+    error: (action, _state, err) => console.error("error:", action.type, err),
+  });
+};
+```
+
+## 开发命令
+
+```bash
+# 运行示例
+npm start
+
+# 测试
+npm test
+
+# 构建（输出 ESM + CJS + d.ts）
+npm run build
+
+# 生成 changeset
+npm run changeset
+
+# 应用版本变更（修改 package.json + CHANGELOG）
+npm run version-packages
+```
+
+## 发布说明
+
+### 一次标准发布流程
+
+1. 开发完成后执行 `npm run changeset`，选择版本语义（patch/minor/major）并填写说明。
+2. 推送分支后，GitHub Actions 会通过 `changesets` 工作流自动维护版本 PR。
+3. 合并版本 PR 后，创建并推送 tag（例如 `v1.2.0`）。
+4. `release.yml` 会在 tag push 时自动执行测试、构建并发布到 npm。
+
+### 发布前准备
+
+- 在 GitHub 仓库 `Settings -> Secrets and variables -> Actions` 配置：
+  - `NPM_TOKEN`：npm automation token
+- 确保仓库权限允许 `contents: write`（用于创建 GitHub Release）
+
+> 说明：README 徽章中的 `OWNER/REPO` 需要替换为你的真实仓库路径。
+
+## License
+
+MIT