CCState：为大型 Web 应用设计的状态管理库

CCState 是一个基于 Signal 的状态管理库。它通过三种语义化的信号类型（State、Computed、Command）实现读写能力隔离，并原生支持 async/await 的异步计算，让状态管理变得简单直观。CCState 与框架无关，可与 React、Vue、Solid.js 等任何 UI 框架无缝集成。它在 秒多 等项目中得到验证，为大规模应用而设计。

快速上手

Signal

Signal 是一个轻量级的描述对象,它本身不存储值,只是一个"引用"或"标识符"。所有 Signal 的值都存储在 Store 中。CCState 提供三种 Signal 类型：

State - 可读写信号，表示原子状态：

1import { state } from "ccstate";
2
3// State 是一个信号，只是声明了状态的存在
4const count$ = state(0);
5const user$ = state({ name: "Alice", age: 30 });
6
7// 值存储在 Store 中
8const store = createStore();
9store.set(count$, 10); // 将值 10 写入 Store
10const value = store.get(count$); // 从 Store 读取值
11

Computed - 只读信号，读取时执行计算逻辑：

1import { computed } from "ccstate";
2
3// Computed 是一个信号，声明了计算逻辑
4// 它本身不存储值，只在被读取时执行计算
5const double$ = computed((get) => get(count$) * 2);
6const userName$ = computed((get) => get(user$).name);
7
8// 读取 Computed 时，执行计算逻辑，计算结果缓存在 Store 中
9const doubled = store.get(double$); // 执行计算: get(count$) * 2
10
11// Computed 内只能读取信号，不能写入
12const invalid$ = computed(({ get, set }) => {
13  // ❌ 编译错误: Computed 的 get 回调中没有 set 参数
14  set(count$, 10);
15});
16

Command - 只写信号，写入时执行业务逻辑：

1import { command } from "ccstate";
2
3// Command 是一个信号，声明了业务逻辑
4// 它本身不存储值，只在被写入时执行逻辑
5const increment$ = command(({ get, set }) => {
6  // Command 内可以读取和写入信号
7  set(count$, get(count$) + 1);
8});
9
10// 写入 Command 时，执行业务逻辑
11store.set(increment$); // 执行: set(count$, get(count$) + 1)
12
13// Command 不能被读取
14// store.get(increment$);  // ❌ 编译错误: Command 不能被读取
15

Store - 状态容器，存储所有 Signal 的值：

1import { createStore } from "ccstate";
2
3// Store 是实际存储值的地方
4const store = createStore();
5
6// Signal 只是标识符，值存储在 Store 中
7store.set(count$, 10); // 将值 10 存入 Store
8const value = store.get(count$); // 从 Store 读取值 10
9

基础使用

通过 Store 读取和修改状态：

1// 读取状态
2const count = store.get(count$); // 0
3const double = store.get(double$); // 0
4
5// 修改 State
6store.set(count$, 10);
7console.log(store.get(count$)); // 10
8console.log(store.get(double$)); // 20（自动重新计算）
9
10// 执行 Command
11store.set(increment$);
12console.log(store.get(count$)); // 11
13

使用 watch 订阅状态变化，当依赖的信号变化时自动执行

1store.watch((get) => {
2  console.log("Count:", get(count$));
3});
4// 输出: Count: 11
5
6store.set(count$, 20);
7// 输出: Count: 20
8

与 React 集成

CCState 通过 ccstate-react 提供 React 绑定，让组件能够响应式地订阅状态变化。

注入 Store

使用 StoreProvider 在应用根组件注入 Store，子组件通过 hooks 访问状态：

1import { createStore } from "ccstate";
2import { StoreProvider } from "ccstate-react";
3
4function App() {
5  const store = createStore();
6
7  return (
8    <StoreProvider value={store}>
9      <Counter />
10    </StoreProvider>
11  );
12}
13

注入 Store 后，子组件无需直接访问 store 对象，所有操作通过 hooks 完成。

重要特性：CCState 中的所有状态（State、Computed、Command）都是全局状态。Store 通过 React 的 useContext 全局注入。所以 signal 可以在任何组件中使用，不受组件层级限制

useGet

useGet 读取状态并自动订阅变化。它实现了细粒度的增量更新：组件只订阅实际访问的状态，只有这些状态变化时才会重新渲染。

1import { useGet } from "ccstate-react";
2
3const count$ = state(0);
4const double$ = computed((get) => get(count$) * 2);
5const message$ = state("Hello");
6
7function Counter() {
8  const count = useGet(count$);
9  const double = useGet(double$);
10  // 注意：这里没有使用 message$
11
12  return (
13    <div>
14      <p>Count: {count}</p>
15      <p>Double: {double}</p>
16    </div>
17  );
18}
19
20// 修改 count$，Counter 会重新渲染
21store.set(count$, 10);
22
23// 修改 message$，Counter 不会重新渲染（未订阅）
24store.set(message$, "World");
25

实现原理：useGet 内部使用 React 18 的 useSyncExternalStore API，通过 store.watch 订阅状态变化。当订阅的 Signal 发生变化时，watch 回调触发组件重新渲染，实现了增量更新。由于 watch 会自动追踪依赖，useGet 无需手动指定依赖数组，不会遗漏或过度订阅。

useSet

useSet 返回一个函数，用于修改 State 或执行 Command。对于 State，返回 setter 函数；对于 Command，返回执行器函数：

1import { useGet, useSet } from "ccstate-react";
2
3const count$ = state(0);
4const increment$ = command(({ get, set }) => {
5  set(count$, get(count$) + 1);
6});
7
8function Counter() {
9  const count = useGet(count$);
10  const setCount = useSet(count$); // 返回修改 State 的函数
11  const increment = useSet(increment$); // 返回执行 Command 的函数
12
13  return (
14    <div>
15      <p>Count: {count}</p>
16      {/* 在事件处理器中调用 setCount */}
17      <button onClick={() => setCount(count + 1)}>+1</button>
18      {/* Command 执行器可以直接作为事件处理器 */}
19      <button onClick={increment}>Increment</button>
20    </div>
21  );
22}
23

重要提示：不要在组件渲染期间直接调用 useSet 返回的函数，应该在事件处理器、useEffect 或其他副作用中调用。

useSet 返回的函数在组件生命周期内保持稳定，可以安全地传递给子组件或作为 useEffect 依赖。

异步状态的统一管理

CCState 提供了四个 hooks 来处理异步状态，它们以不同的方式管理 loading 状态。

useResolved：返回异步结果，loading 时返回 undefined：

1import { useResolved } from "ccstate-react";
2
3const userId$ = state("123");
4const user$ = computed(async (get) => {
5  const id = get(userId$);
6  const resp = await fetch([`/api/users/${id}`](https://xplanc.org/primers/document/zh/10.Bash/90.%E5%B8%AE%E5%8A%A9%E6%89%8B%E5%86%8C/EX.id.md));
7  return resp.json();
8});
9
10function UserProfile() {
11  const user = useResolved(user$);
12
13  // loading 时 user 为 undefined
14  if (user === undefined) {
15    return <div>Loading...</div>;
16  }
17
18  return <div>User: {user.name}</div>;
19}
20

useLastResolved：当依赖变化触发重新计算时，保留上一次成功的结果，避免闪烁：

1import { useLastResolved } from "ccstate-react";
2
3const userId$ = state("123");
4const user$ = computed(async (get) => {
5  const id = get(userId$);
6  const resp = await fetch([`/api/users/${id}`](https://xplanc.org/primers/document/zh/10.Bash/90.%E5%B8%AE%E5%8A%A9%E6%89%8B%E5%86%8C/EX.id.md));
7  return resp.json();
8});
9
10function UserProfile() {
11  const user = useLastResolved(user$);
12
13  // 首次 loading 时为 undefined
14  return <div>User: {user?.name ?? "Loading..."}</div>;
15}
16
17// 使用场景：用户切换 userId 时，保留旧用户信息直到新用户加载完成
18store.set(userId$, "123"); // 加载用户 123
19// 显示: "User: Alice"
20
21store.set(userId$, "456"); // 触发 user$ 重新计算
22// useResolved 会返回 undefined，显示 "Loading..."
23// useLastResolved 仍返回 Alice（上一次的结果），显示 "User: Alice"
24// 等新数据加载完成后，才更新为 "User: Bob"
25

useLoadable：手动处理 loading、hasData、hasError 三种状态：

1import { useLoadable } from "ccstate-react";
2
3function UserProfile() {
4  const userLoadable = useLoadable(user$);
5
6  if (userLoadable.state === "loading") {
7    return <div>Loading...</div>;
8  }
9
10  if (userLoadable.state === "hasError") {
11    return <div>Error: {userLoadable.error.message}</div>;
12  }
13
14  return <div>User: {userLoadable.data.name}</div>;
15}
16

useLastLoadable：类似 useLoadable，但保留上一次成功的数据：

对比总结：

状态管理的核心挑战

状态管理是现代 Web 应用的基础设施，它需要解决派生状态计算、性能优化、异步处理、异常管理、测试和调试等一系列挑战。

派生状态计算

派生状态（Derived State）指基于其他状态计算得出的状态。比如购物车商品列表是原始状态，总价就是派生状态。状态管理需要解决派生状态的以下问题：

1. 如何收集依赖：派生状态可能根据条件依赖不同的原始状态（如 condition ? a : b），如何自动追踪这些动态变化的依赖？
2. 是否需要重新计算：当原始状态变化时，如何高效判断哪些派生状态的缓存已失效，需要重新计算？
3. 重新计算的时机：什么时候重新计算？
4. 循环依赖检测：如何检测并处理 A 依赖 B、B 依赖 A 的循环依赖？
5. 菱形依赖的一致性保证：在菱形依赖结构中（A 依赖 B 和 C，B 和 C 都依赖 D），当 D 变化时，如何保证 A 不会读取到 B 和 C 的不一致状态？

CCState 采用 动态收集依赖 + 版本号机制 的策略，重新计算的时机根据 Computed 是否被订阅有所不同，下一节介绍

1. 动态收集依赖: 在执行计算时，通过 get 回调自动收集依赖关系；每次重新计算都会重新收集依赖：

1import { state, computed, createStore } from "ccstate";
2
3const useDiscount$ = state(false);
4const originalPrice$ = state(100);
5const discountPrice$ = state(80);
6
7// 根据条件动态依赖不同的状态
8const finalPrice$ = computed((get) => {
9  return get(useDiscount$) ? get(discountPrice$) : get(originalPrice$);
10});
11
12const store = createStore();
13store.get(finalPrice$); // 100（当前依赖 useDiscount$ 和 originalPrice$）
14
15// 修改 discountPrice$ 不会触发重新计算（未被依赖）
16store.set(discountPrice$, 70);
17store.get(finalPrice$); // 100（使用缓存）
18
19// 切换折扣后，依赖关系自动更新
20store.set(useDiscount$, true);
21store.get(finalPrice$); // 70（重新计算，现在依赖 useDiscount$ 和 discountPrice$）
22

2. 版本号判断是否需要重新计算：CCState 为每个状态维护版本号，派生状态记录依赖的版本快照：

1const cartItems$ = state([
2  { id: 1, price: 100, quantity: 2 },
3  { id: 2, price: 50, quantity: 3 },
4]);
5
6const totalPrice$ = computed((get) => {
7  const items = get(cartItems$);
8  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
9});
10
11const store = createStore();
12// totalPrice$ 记录 cartItems$ 的版本号
13store.get(totalPrice$);
14
15// 修改 cartItems$ 时，版本号递增
16store.set(cartItems$, [{ id: 1, price: 100, quantity: 3 }]);
17
18// 下次访问时，比对版本号发现不一致，重新计算
19store.get(totalPrice$); // 300
20

只有值真正变化时才递增版本号，避免不必要的下游更新。

3. 循环依赖检测

CCState 通过缓存机制处理循环依赖。在未订阅（unmounted）状态下，循环依赖会返回缓存值，可能是 undefine，这是一个问题；在订阅（mounted）状态下会抛出错误：

1// 创建循环依赖
2const a$ = computed((get) => get(b$) + 1);
3const b$ = computed((get) => get(a$) + 1);
4
5const store = createStore();
6
7// 未订阅时：使用缓存机制，返回 NaN，不会抛出错误
8const result = store.get(a$); // 返回数值（基于缓存）
9
10// 订阅时：检测到循环依赖，抛出错误
11store.watch((get) => {
12  get(a$); // 这里会抛出 RangeError: Maximum call stack size exceeded
13});
14

4. 菱形依赖的一致性保证

CCState 在 get(computed) 时，会计算所有的依赖；在通过 watch 订阅 Signal 时，没有 set 操作。所以，这个问题不会发生

派生状态的性能优化

派生状态会带来以下性能问题

• 不必要的计算：即使状态未被使用，也会触发计算，浪费 CPU 资源
• 级联重新计算：要读取一个派生状态的值，需要重新计算它依赖的所有派生状态
• 立即更新订阅：每一次状态的修改，都会触发订阅的回调。会导致订阅者被重复通知，造成计算冗余

CCState 的解决方案

1. 按需计算：Computed 只在被订阅（mounted）时才会响应式更新，未订阅时采用懒计算：

1const base$ = state(0);
2const expensive$ = computed((get) => {
3  const value = get(base$);
4  // 复杂计算
5  return heavyComputation(value);
6});
7
8store.set(base$, 1); // expensive$ 不会立即计算
9
10// 只有在 watch 订阅后，才会响应式更新
11store.watch((get) => {
12  console.log(get(expensive$)); // 此时 expensive$ 进入 mounted 状态
13});
14
15store.set(base$, 2); // 现在会触发 expensive$ 的计算
16

2. 级联计算优化：

在级联 Computed 依赖链中（如 A 依赖 B，B 依赖 C），读取 A 的值时，需要先判断 B 是否需要重新计算，而判断 B 又需要检查 C。这种层层检查会带来性能开销。CCState 针对这个问题的优化策略取决于读取方式

通过 Store.get、Computed.get、Command.get 读取：没有优化：需要遍历整个依赖链，逐个检查依赖的版本号来判断是否需要重新计算。

1const a$ = state(1);
2const b$ = computed((get) => get(a$) * 2);
3const c$ = computed((get) => get(b$) + 10);
4
5const store = createStore();
6
7// 通过 store.get 读取时，仍需要遍历 c$ -> b$ -> a$ 的依赖链
8store.get(c$); // 需要检查整个依赖链
9store.get(c$); // 再次读取，仍需要遍历整个依赖链
10

通过 Watch.get 读取：可能有优化：

• set 修改 State 时，触发依赖该 State 的 watch 回调
• 在执行 watch 回调之前，CCState 会沿着反向依赖链，提前计算部分 Computed（具体哪些 Computed 会被提前计算，取决于反向依赖关系）
• 当 watch.get 读取 Computed 时，如果某个 Computed 被提前计算了，则不需要再次计算，直接返回即可

1const a$ = state(1);
2const b$ = computed((get) => {
3  console.log("Computing b$");
4  return get(a$) * 2;
5});
6const c$ = computed((get) => {
7  console.log("Computing c$");
8  return get(b$) + 10;
9});
10
11const store = createStore();
12
13// 订阅 c$，建立反向依赖链：a$ -> b$ -> c$ -> watch
14store.watch((get) => {
15  console.log("Result:", get(c$));
16});
17// 输出:
18// Computing b$
19// Computing c$
20// Result: 12
21
22// 修改 a$，触发 watch
23store.set(a$, 2);
24// 输出:
25// Computing b$ ← set 时，沿反向依赖链提前计算
26// Computing c$ ← set 时，沿反向依赖链提前计算
27// Result: 14 ← watch.get 读取时，b$ 和 c$ 已被提前计算，直接返回
28

3. 批量更新订阅：批量更新是指在一次操作中修改多个原子状态时，只触发一次副作用回调。这里 CCState 没有优化，在一次 Command 中会触发多次 Watch 回调：

1const updateName$ = command(({ set }) => {
2  set(firstName$, "John"); // 第一次修改
3  set(lastName$, "Doe"); // 第二次修改
4  // 批量更新：只触发一次 watch
5  // 非批量更新：触发两次 watch
6});
7

CCState 每次状态修改都会立即触发 watch 回调。原因有以下几个：

1. 更简单的心智模型：状态变化即生效，便于理解和调试，开发者可以准确预期每次修改的影响
2. CCState 不推荐使用 订阅更新。当前只在视图层使用，比如 React 使用 useGet 订阅状态的变化去修改视图，这里 React 本身有增量更新的优化，所以对性能影响较小。
3. 异步 Command 的批量边界不明确：在异步操作中，很难确定批量更新的边界。如果做批量更新，需要在 await 前触发一次更新，还是等整个 command 完成后再触发？这会让行为变得难以预测。

1const asyncCommand$ = command(async ({ set }) => {
2  set(a$, 1);
3  await delay(100); // 这里算不算 command 结束？
4  set(b$, 2);
5});
6

当然，作者认为可以出一个只有 同步 回调的批量更新 comamnd 。也能优化一部分订阅更新的性能。

异步处理

CCState 通过原生支持异步，Computed 自动处理竞态让异步变得简单

1. 异步控制流程：CCState 原生支持 async/await，无需额外概念：

1// 异步获取用户信息
2const userId$ = state("");
3const user$ = computed(async (get) => {
4  const userId = get(userId$);
5  if (!userId) return null;
6
7  // 直接使用 async/await
8  const resp = await fetch(`/api/users/${userId}`);
9  return resp.json();
10});
11
12const store = createStore();
13store.set(userId$, "user123");
14
15// get 返回 Promise
16const user = await store.get(user$);
17

2. 处理竞态：CCState 在 Computed 中内置了 AbortSignal，自动处理竞态：

1const searchQuery$ = state("");
2const searchResults$ = computed(async (get, { signal }) => {
3  const query = get(searchQuery$);
4  if (!query) return [];
5
6  // signal 会在新计算开始时自动 abort
7  const resp = await fetch([`/api/search?q=${query}`](https://xplanc.org/primers/document/zh/03.HTML/EX.HTML%20%E5%85%83%E7%B4%A0/EX.q.md), { signal });
8  return resp.json();
9});
10
11// 快速输入 "a" -> "ab" -> "abc"
12store.set(searchQuery$, "a"); // 发起请求 1
13store.set(searchQuery$, "ab"); // 请求 1 被 abort，发起请求 2
14store.set(searchQuery$, "abc"); // 请求 2 被 abort，发起请求 3
15// 只有请求 3 的结果会被使用
16

异常管理

在复杂的状态管理中，异常处理面临以下挑战：

• 派生状态异常传播：派生状态中的错误如何传递到上层调用者？
• 错误恢复：错误发生后如何重置状态或重试？

CCState 的解决方案

1. 派生状态异常传播：Computed 中抛出的异常会自动传播到调用方

1const userId$ = state("invalid-id");
2
3const user$ = computed(async (get) => {
4  const userId = get(userId$);
5  const resp = await fetch(`/api/users/${userId}`);
6
7  if (!resp.ok) {
8    throw new Error(`Failed to fetch user: ${resp.status}`);
9  }
10
11  return resp.json();
12});
13
14// 在其他 Computed 中，异常会继续传播
15const userName$ = computed(async (get) => {
16  const user = await get(user$); // 如果 user$ 抛出异常，这里会直接抛出
17  return user.name;
18});
19
20// 调用方可以使用 try/catch 捕获异常
21try {
22  const user = await store.get(user$);
23} catch (error) {
24  console.error("Error loading user:", error);
25}
26

CCState 使用与正常值相同的依赖追踪机制处理异常。当 user$ 抛出异常时，异常会被缓存；依赖它的 userName$ 读取时会得到同样的异常。

2. 错误恢复

通过修改上游 State 来触发重新计算，实现错误恢复或重试：

1const retryCount$ = state(0);
2
3const data$ = computed(async (get) => {
4  get(retryCount$); // 依赖 retryCount$，修改它会触发重新计算
5  const resp = await fetch("/api/data");
6  if (!resp.ok) throw new Error("Failed");
7  return resp.json();
8});
9
10// 重试：修改 retryCount$ 触发重新计算
11store.set(retryCount$, (x) => x + 1);
12

CCState 让异常处理与常规 JavaScript 代码保持一致，无需学习特殊的错误处理模式。异常和正常值使用统一的依赖追踪和缓存机制。

可测试性

CCState 通过 状态隔离、原生支持异步、视图与状态分离三个特点，让测试变得简单。

状态隔离：每个测试创建独立的 Store，天然隔离

1import { test, expect } from "vitest";
2import { state, computed, createStore } from "ccstate";
3
4test("测试 1", () => {
5  const store = createStore(); // 独立的 store
6  const count$ = state(0);
7  store.set(count$, 10);
8  expect(store.get(count$)).toBe(10);
9});
10
11test("测试 2", () => {
12  const store = createStore(); // 另一个独立的 store
13  const count$ = state(0); // 同名 signal，但完全隔离
14  expect(store.get(count$)).toBe(0); // 不受测试 1 影响
15});
16

原生支持异步：异步操作直接使用同步逻辑或简单的 mock 数据，无需复杂的异步模拟

1test("异步用户加载", async () => {
2  const store = createStore();
3
4  const userId$ = state("123");
5  const user$ = computed(async (get) => {
6    const userId = await get(userId$);
7    // 测试中直接返回 mock 数据，无需 mock fetch
8    return { id: userId, name: "Test User" };
9  });
10
11  const user = await store.get(user$);
12  expect(user.name).toBe("Test User");
13});
14
15// 或者测试实际的 fetch 逻辑，使用标准的 mock 工具
16test("实际 fetch 测试", async () => {
17  const store = createStore();
18
19  // 使用标准的 fetch mock
20  global.fetch = vi.fn().mockResolvedValue({
21    json: async () => ({ id: "123", name: "Test User" }),
22  });
23
24  const user$ = computed(async () => {
25    const resp = await fetch("/api/user");
26    return resp.json();
27  });
28
29  const user = await store.get(user$);
30  expect(user.name).toBe("Test User");
31});
32