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

安装

npm install fox-mini-x

快速开始

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

支持两种调用方式：

mapState(["count"]);
mapState("user", ["name"]);

createNamespacedHelpers(namespace)

返回绑定命名空间的辅助函数：

import { createNamespacedHelpers } from "fox-mini-x";

const { mapState, mapGetters, mapMutations, mapActions } =
  createNamespacedHelpers("user");

模块与命名空间示例

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 生命周期示例

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),
  });
};

开发命令

# 运行示例
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