ccstate 2.1.0 → 3.0.0

package/README.md

@@ -10,8 +10,6 @@
 [![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/e7h4n/ccstate)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-English | [中文](README-zh.md)
-
 CCState is a semantic, strict, and flexible state management library suitable for medium to large single-page applications with complex state management needs.
 
 The name of CCState comes from three basic data types: computed, command, and state.
@@ -21,7 +19,7 @@ The name of CCState comes from three basic data types: computed, command, and st
 - 💯 Simple & Intuitive: Crystal-clear API design with just 3 data types and 2 operations
 - ✅ Rock-solid Reliability: Comprehensive test coverage reaching 100% branch coverage
 - 🪶 Ultra-lightweight: Zero dependencies, only 500 lines of core code
-- 💡 Framework Agnostic: Seamlessly works with React, Vanilla JS, or any UI framework
+- 💡 Framework Agnostic: Seamlessly works with [React](docs/react.md), [Vue](docs/vue.md), or any UI framework
 - 🚀 Blazing Fast: Optimized performance from day one, 2x-7x faster than Jotai across scenarios
 
 ## Getting Started
@@ -64,7 +62,7 @@ Use `useGet` and `useSet` hooks in React to get/set data, and use `useResolved`
 
 ```jsx
 // App.js
-import { useGet, useSet, useResolved } from 'ccstate';
+import { useGet, useSet, useResolved } from 'ccstate-react';
 import { userId$, user$ } from './data';
 
 export default function App() {
@@ -93,8 +91,8 @@ Use `createStore` and `StoreProvider` to provide a CCState store to React, all s
 
 ```tsx
 // main.jsx
-import { createStore, StoreProvider } from 'ccstate';
-import { StrictMode } from 'react';
+import { createStore } from 'ccstate';
+import { StoreProvider } from 'ccstate-react';
 import { createRoot } from 'react-dom/client';
 
 import App from './App';
@@ -104,11 +102,9 @@ const root = createRoot(rootElement);
 
 const store = createStore();
 root.render(
-  <StrictMode>
-    <StoreProvider value={store}>
-      <App />
-    </StoreProvider>
-  </StrictMode>,
+  <StoreProvider value={store}>
+    <App />
+  </StoreProvider>,
 );
 ```
 
@@ -134,11 +130,14 @@ store.get(userId$); // 0
 store.set(userId$, 100);
 store.get(userId$); // 100
 
-const callback$ = state<(() => void) | undefined>(undefined);
-store.set(callback$, () => {
-  console.log('awesome ccstate');
+const user$ = state<({
+  name: 'e7h4n',
+  avatar: 'https://avatars.githubusercontent.com/u/813596',
+} | undefined>(undefined);
+store.set({
+  name: 'yc-kanyun',
+  avatar: 'https://avatars.githubusercontent.com/u/168416598'
 });
-store.get(callback$)(); // console log 'awesome ccstate'
 ```
 
 These examples should be very easy to understand. You might notice a detail in the examples: all variables returned by `state` have a `$` suffix. This is a naming convention used to distinguish an CCState data type from other regular types. CCState data types must be accessed through the store's get/set methods, and since it's common to convert an CCState data type to a regular type using get, the `$` suffix helps avoid naming conflicts.
@@ -283,155 +282,11 @@ That's it! Next, you can learn how to use CCState in React.
 
 ## Using in React
 
-To begin using CCState in a React application, you must utilize the `StoreProvider` to provide a store for the hooks.
-
-```jsx
-// main.tsx
-import { createStore, StoreProvider } from 'ccstate';
-import { App } from './App';
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-
-const store = createStore();
-
-createRoot(document.getElementById('root')).render(
-  <StrictMode>
-    <StoreProvider value={store}>
-      <App />
-    </StoreProvider>
-  </StrictMode>,
-);
-```
-
-All descendant components within the `StoreProvider` will use the provided store as the caller for `get` and `set` operations.
-
-You can place the `StoreProvider` inside or outside of `StrictMode`; the functionality is the same.
-
-### Retrieving Values
-
-The most basic usage is to use `useGet` to retrieve the value from State or Computed.
-
-```jsx
-// data/count.ts
-import { state } from 'ccstate';
-export const count$ = state(0);
-
-// App.tsx
-import { useGet } from 'ccstate';
-import { count$ } from './data/count';
-
-function App() {
-  const count = useGet(count$);
-  return <div>{count}</div>;
-}
-```
-
-`useGet` returns a `State` or a `Computed` value, and when the value changes, `useGet` triggers a re-render of the component.
-
-`useGet` does not do anything special with `Promise` values. In fact, `useGet` is equivalent to a single `store.get` call, plus a `store.sub` to ensure reactive updates to the React component.
-
-Two other useful hooks are available when dealing with `Promise` values. First, we introduce `useLoadable`.
-
-```jsx
-// data/user.ts
-import { computed } from 'ccstate';
-
-export const user$ = computed(async () => {
-  return fetch('/api/users/current').then((res) => res.json());
-});
-
-// App.tsx
-import { useLoadable } from 'ccstate';
-import { user$ } from './data/user';
-
-function App() {
-  const user_ = useLoadable(user$);
-  if (user_.state === 'loading') return <div>Loading...</div>;
-  if (user_.state === 'error') return <div>Error: {user_.error.message}</div>;
-
-  return <div>{user_.data.name}</div>;
-}
-```
-
-`useLoadable` accepts Value/Computed that returns a `Promise` and wraps the result in a `Loadable` structure.
-
-```typescript
-type Loadable<T> =
-  | {
-      state: 'loading';
-    }
-  | {
-      state: 'hasData';
-      data: T;
-    }
-  | {
-      state: 'hasError';
-      error: unknown;
-    };
-```
-
-This allows you to render loading and error states in JSX based on the state. `useLoadable` suppresses exceptions, so it will not trigger an `ErrorBoundary`.
-
-Another useful hook is `useResolved`, which always returns the resolved value of a `Promise`.
-
-```jsx
-// App.tsx
-import { useResolved } from 'ccstate';
-import { user$ } from './data/user';
-
-function App() {
-  const user = useResolved(user$);
-  return <div>{user?.name}</div>;
-}
-```
-
-`useResolved` only returns the parameter passed to the resolve function so that it will return `undefined` during loading and when encountering error values. Like `useLoadable`, `useResolved` also suppresses exceptions. In fact, `useResolved` is a simple wrapper around `useLoadable`.
-
-```typescript
-// useResolved.ts
-import { useLoadable } from './useLoadable';
-import type { Computed, State } from '../core';
-
-export function useResolved<T>(atom: State<Promise<T>> | Computed<Promise<T>>): T | undefined {
-  const loadable = useLoadable(atom);
-  return loadable.state === 'hasData' ? loadable.data : undefined;
-}
-```
-
-### useLastLoadable & useLastResolved
+[Using in React](docs/react.md)
 
-In some scenarios, we want a refreshable Promise Computed to maintain its previous result during the refresh process instead of showing a loading state. CCState provides `useLastLoadable` and `useLastResolved` to achieve this functionality.
+## Using in Vue
 
-```jsx
-import { useLoadable } from 'ccstate';
-import { user$ } from './data/user';
-
-function App() {
-  const user_ = useLastLoadable(user$); // Keep the previous result during new user$ request, without triggering loading state
-  if (user_.state === 'loading') return <div>Loading...</div>;
-  if (user_.state === 'error') return <div>Error: {user_.error.message}</div>;
-
-  return <div>{user_.data.name}</div>;
-}
-```
-
-`useLastResolved` behaves similarly - it always returns the last resolved value from a Promise Atom and won't reset to `undefined` when a new Promise is generated.
-
-### Updating State / Triggering Command
-
-The `useSet` hook can be used to update the value of State, or trigger Command. It returns a function equivalent to `store.set` when called.
-
-```jsx
-// App.tsx
-import { useSet } from 'ccstate';
-import { count$ } from './data/count';
-
-function App() {
-  const setCount = useSet(count$);
-  // setCount(x => x + 1) is equivalent to store.set(count$, x => x + 1)
-  return <button onClick={() => setCount((x) => x + 1)}>Increment</button>;
-}
-```
+[Using in Vue](docs/vue.md)
 
 ### Testing & Debugging
 
@@ -457,12 +312,12 @@ Here are some tips to help you better debug during testing.
 Use `ConsoleInterceptor` to log most store behaviors to the console during testing:
 
 ```typescript
-import { createConsoleDebugStore, state, computed, command } from 'ccstate';
+import { createDebugStore, state, computed, command } from 'ccstate';
 
 const base$ = state(1, { debugLabel: 'base$' });
 const derived$ = computed((get) => get(base$) * 2);
 
-const store = createConsoleDebugStore([base$, 'derived'], ['set', 'sub']); // log sub & set actions
+const store = createDebugStore([base$, 'derived'], ['set', 'sub']); // log sub & set actions
 store.set(base$, 1); // console: SET [V0:base$] 1
 store.sub(
   derived$,
@@ -472,13 +327,17 @@ store.sub(
 
 ## Concept behind CCState
 
-CCState is inspired by Jotai. While Jotai is a great state management solution that has benefited the Motiff project significantly, as our project grew larger, especially with the increasing number of states (10k~100k atoms), we felt that some of Jotai's design choices needed adjustments, mainly in these aspects:
+CCState is inspired by Jotai. So everyone will ask questions: What's the ability of CCState that Jotai doesn't have?
+
+The answer is: CCState intentionally has fewer features, simpler concepts, and less "magic" under the hood.
+
+While Jotai is a great state management solution that has benefited the Motiff project significantly, as our project grew larger, especially with the increasing number of states (10k~100k atoms), we felt that some of Jotai's design choices needed adjustments, mainly in these aspects:
 
 - Too many combinations of atom init/setter/getter methods, need simplification to reduce team's mental overhead
 - Should reduce reactive capabilities, especially the `onMount` capability - the framework shouldn't provide this ability
 - Some implicit magic operations, especially Promise wrapping, make the application execution process less transparent
 
-To address these issues, I created CCState to express my thoughts on state management. Before detailing the differences from Jotai, we need to understand CCState's data types and subscription system.
+To address these issues, I got an idea: "What concepts in Jotai are essential? And which concepts create mental overhead for developers?". Rather than just discussing it theoretically, I decided to try implementing it myself. So I created CCState to express my thoughts on state management. Before detailing the differences from Jotai, we need to understand CCState's data types and subscription system.
 
 ### More semantic data types
 
@@ -513,7 +372,39 @@ function setupPage() {
 
 The consideration here is to avoid having callbacks depend on the Store object, which was a key design consideration when creating CCState. In CCState, `sub` is the only API with reactive capabilities, and CCState reduces the complexity of reactive computations by limiting Store usage.
 
-CCState does not have APIs like `onMount`. This is because CCState considers `onMount` to be fundamentally an effect, and providing APIs like `onMount` in `computed` would make the computation process non-idempotent.
+In Jotai, there are no restrictions on writing code that uses sub within a sub callback:
+
+```typescript
+store.sub(targetAtom, () => {
+  if (store.get(fooAtom)) {
+    store.sub(barAtom, () => {
+      // ...
+    });
+  }
+});
+```
+
+In CCState, we can prevent this situation by moving the `Command` definition to a separate file and protecting the Store.
+
+```typescript
+// main.ts
+import { callback$ } from './callbacks'
+import { foo$ } from './states
+
+function initApp() {
+  const store = createStore()
+  store.sub(foo$, callback$)
+  // do not expose store to outside
+}
+
+// callbacks.ts
+
+export const callback$ = command(({ get, set }) => {
+  // there is no way to use store sub
+})
+```
+
+Therefore, in CCState, the capability of `sub` is intentionally limited. CCState encourages developers to handle data consistency updates within `Command`, rather than relying on subscription capabilities for reactive data updates. In fact, in a React application, CCState's `sub` is likely only used in conjunction with `useSyncExternalStore` to update views, while in all other scenarios, the code is completely moved into Commands.
 
 ### Avoid `useEffect` in React
 
@@ -581,6 +472,349 @@ root.render(
 );
 ```
 
+### Less Magic
+
+#### No `onMount`: Maintaining Pure State Semantics
+
+CCState intentionally omits `onMount` to preserve the side-effect-free nature of `Computed` and `State`. This design choice emphasizes clarity and predictability over convenience.
+
+Let's examine a common pattern in Jotai and understand why CCState takes a different approach. [Consider the following scenario](https://codesandbox.io/p/sandbox/gkk43v):
+
+```typescript
+// atom.ts
+const countAtom = atom(0);
+countAtom.onMount = (setAtom) => {
+  const timer = setInterval(() => {
+    setAtom((x) => x + 1);
+  }, 1000);
+  return () => {
+    clearInterval(timer);
+  };
+};
+
+// App.tsx
+function App() {
+  const count = useAtomValue(countAtom)
+  return <div>{count}</div>
+}
+```
+
+It looks pretty cool, right? Just by using `useAtomValue` in React, you get an auto-incrementing timer. However, this means that subscribing to a `State` can potentially have side effects. Because it has side effects, we need to be very careful handling these side effects in scenarios like `useExternalStore` and `StrictMode`. In CCState, such timer auto-increment operations can only be placed in a `Command`.
+
+```tsx
+// logic.ts
+export const count$ = state(0); // state is always effect-less
+
+export const setupTimer$ = command(({ set }) => {
+  // command is considered to always have side effects
+  const timer = setInterval(() => {
+    set(count$, (x) => x + 1);
+  }, 1000);
+  return () => {
+    clearInterval(timer);
+  };
+});
+
+// Must explicitly enable side effects in React
+// App.tsx
+function App() {
+  const count = useGet(count$);
+  const setupTimer = useSet(setupTimer$);
+
+  // Rendering App has side effects, so we explicitly enable them
+  useEffect(() => {
+    return setupTimer();
+  }, []);
+
+  return <div>{count}</div>;
+}
+
+// A more recommended approach is to enable side effects outside of React
+// main.ts
+store.sub(
+  // sub is always effect-less to any State
+  count$,
+  command(() => {
+    // ... onCount
+  }),
+);
+store.set(setupTimer$); // must setup effect explicitly
+
+// ...
+
+// The pure effect-less rendering process
+root.render(function App() {
+  const count = useGet(count$);
+
+  return <div>{count}</div>;
+});
+```
+
+I'm agree with [explicit is better than implicit](https://peps.python.org/pep-0020/), so CCState removes the `onMount` capability.
+
+#### No `loadable` & `unwrap`
+
+Jotai provides `loadable` and `unwrap` to handle Promise Atom, to convert them to a flat loading state atom. To implement this functionality, it inevitably needs to use `onMount` to subscribe to Promise changes and then modify its own return value.
+
+As mentioned in the previous section, CCState does not provide `onMount`, so `loadable` and `unwrap` are neither present nor necessary in CCState. Instead, React hooks `useLoadable` and `useResolved` are provided as alternatives. The reason for this design is that I noticed a detail - only within a subscription system (like React's rendering part) do we need to convert a Promise into a loading state:
+
+```tsx
+// Jotai's example, since try/catch and async/await cannot be used in JSX, loadable is required to flatten the Promise
+const userLoadableAtom = loadable(user$);
+function User() {
+  const user = useAtomValue(userLoadableAtom);
+  if (user.state === 'loading') return <div>Loading...</div>;
+  if (user.state === 'error') return <div>Error: {user.error.message}</div>;
+  return <div>{user.data.name}</div>;
+}
+```
+
+Or use loadable in the sub callback.
+
+```ts
+// Jotai's example
+const userLoadableAtom = loadable(user$);
+
+store.sub(userLoadableAtom, () => {
+  // Notice how similar this is to the JSX code above
+  const user = store.get(userLoadableAtom);
+  if (user.state === 'loading') return;
+  if (user.state === 'error') return;
+
+  // ...
+});
+```
+
+CCState intentionally avoids overuse of the subscription pattern, encouraging developers to write state changes where they originate rather than where they are responded to.
+
+```ts
+// CCState's example, avoid use sub pattern to invoke effect
+const updateUserId$ = command(({ set, get }) => {
+  // retrieve userId from somewhere
+  set(userId$, USER_ID)
+
+  set(connectRoom$)
+})
+
+const connectRoom$ = command({ set, get }) => {
+  const user = await get(user$)
+  // ... prepare connection for room
+})
+```
+
+In React's subscription-based rendering system, I use `useEffect` to introduce subscription to Promises. The code below shows the actual implementation of `useLoadable`.
+
+```ts
+function useLastLoadable<T>(atom: State<Promise<T>> | Computed<Promise<T>>): Loadable<T> {
+  const promise = useGet(atom);
+
+  const [promiseResult, setPromiseResult] = useState<Loadable<T>>({
+    state: 'loading',
+  });
+
+  useEffect(() => {
+    const ctrl = new AbortController();
+    const signal = ctrl.signal;
+
+    void promise
+      .then((ret) => {
+        if (signal.aborted) return;
+
+        setPromiseResult({
+          state: 'hasData',
+          data: ret,
+        });
+      })
+      .catch((error: unknown) => {
+        // ...
+      });
+
+    return () => {
+      ctrl.abort();
+    };
+  }, [promise]);
+
+  return promiseResult;
+}
+```
+
+Finally, CCState only implements Promise flattening in the React-related range, that's enough. By making these design choices, CCState maintains a cleaner separation of concerns, makes side effects more explicit, and reduces the overall complexity of state management. While this might require slightly more explicit code in some cases, it leads to more maintainable and predictable applications.
+
+## Technical Details
+
+### When Computed Values Are Evaluated
+
+The execution of `read` function in `Computed` has several strategies:
+
+1. If the `Computed` is not directly or indirectly subscribed, it only be evaluated when accessed by `get`
+   1. If the version number of other `Computed` | `State` accessed by the previous `read` is unchanged, use the result of the last `read` without re-evaluating it
+   2. Otherwise, re-evaluate `read` and mark its version number +1
+2. Otherwise, if the `Computed` is directly or indirectly subscribed, it will constantly be re-evaluated when its dependency changes
+
+I mentioned "directly or indirectly subscribed" twice. Here, we use a simpler term to express it. If a `Computed | Value` is directly or indirectly subscribed, we consider it to be _mounted_. Otherwise, it is deemed to be _unmounted_.
+
+Consider this example:
+
+```typescript
+const base$ = state(0);
+const branch$ = state('A');
+const derived$ = computed((get) => {
+  if (get(branch$) !== 'B') {
+    return 0;
+  } else {
+    return get(base$) * 2;
+  }
+});
+```
+
+In this example, `derived$` is not directly or indirectly subscribed, so it is always in the _unmounted_ state. At the same time, it has not been read, so it has no dependencies. At this point, resetting `base$` / `branch$` will not trigger the recomputation of `derived$`.
+
+```
+store.set(base$, 1) // will not trigger derived$'s read
+store.set(branch$, 'C') // will not trigger derived$'s too
+```
+
+Once we read `derived$`, it will automatically record a dependency array.
+
+```typescript
+store.get(derived$); // return 0 because of branch$ === 'A'
+```
+
+At this point, the dependency array of `derived$` is `[branch$]`, because `derived$` did not access `base$` in the previous execution. Although CCState knows that `derived$` depends on `branch$`, because `branch$` is not mounted, the re-evaluation of `derived$` is lazy.
+
+```typescript
+store.set(branch$, 'D'); // will not trigger derived$'s read, until next get(derived$)
+```
+
+Once we mount `derived$` by `sub`, all its direct and indirect dependencies will enter the _mounted_ state.
+
+```typescript
+store.sub(
+  derived$,
+  command(() => void 0),
+);
+```
+
+The mount graph in CCState is `[derived$, [branch$]]`. When `branch$` is reset, `derived$` will be re-evaluated immediately, and all subscribers will be notified.
+
+```typescript
+store.set(branch$, 'B'); // will trigger derived$'s read
+```
+
+In this re-evaluation, the dependency array of `derived$` is updated to `[branch$, base$]`, so `base$` will also be _mounted_. Any modification to `base$` will immediately trigger the re-evaluation of `derived$`.
+
+```typescript
+store.set(base$, 1); // will trigger derived$'s read and notify all subscribers
+```
+
+[Here's an example](https://codesandbox.io/p/sandbox/ds6p44). Open preview in an independent window to check the console output. If you hide the double output and click increment, you will only see the `set` log.
+
+```
+[R][SET] V1:count$
+    arg: – [function] (1)
+    ret: – undefined
+```
+
+Click show to make double enter the display state, and you can see the `set` `showDouble$` log and the `double$` evaluation log.
+
+```
+[R][SET] V0:showDouble$
+    arg: – [function] (1)
+    ret: – undefined
+
+[R][CPT] C2:doubleCount$
+    ret: – 14
+```
+
+The abbreviation `CPT` represents `Computed` evaluation, not just a simple read operation. You can also try modifying the parameters of `createDebugStore` in the code to include `get` in the logs, and you'll find that not every `get` triggers a `Computed` evaluation.
+
+Click increment to see the `set` trigger the `Computed` evaluation.
+
+```
+[R][SET] V1:count$
+    arg: – [function] (1)
+    [R][CPT] C2:doubleCount$
+        ret: – 16
+    ret: – undefined
+```
+
+### How to Isolate Effect-less Code
+
+CCState strives to isolate effect-less code through API capability restrictions and thus introduces two accessor APIs: `get` and `set`. I remember when I first saw Jotai, I raised a question: why can't we directly use the Atom itself to read and write state, just like signals do?
+
+Most state libraries allow you to directly read and write state once you get the state object:
+
+```typescript
+// Zustand
+const useStore = create((set) => {
+  return {
+    count: 0,
+    updateCount: () => {
+      set({
+        count: (x) => x + 1,
+      });
+    },
+  };
+});
+useStore.getState().count; // read count is effect-less
+useStore.getState().updateCount(); // update count invoke effect
+
+// RxJS
+const count$ = new BehaviorSubject(0);
+count$.value; // read count is effect-less
+count$.next(1); // next count invoke effect
+
+// Signals
+const counter = signal(0);
+counter.value; // read value is effect-less
+counter.value = 1; // write value invoke effect
+```
+
+So, these libraries cannot isolate effect-less code. Jotai and CCState choose to add a wrapper layer to isolate effect-less code.
+
+```typescript
+const count$ = state(0);
+const double$ = computed((get) => {
+  get(count$); // read count$ is effect-less
+  // In this scope, we can't update any state
+});
+const updateDouble$ = command(({ get, set }) => {
+  // This scope can update the state because it has `set` method
+  set(count$, get(count$) * 2);
+});
+```
+
+Isolating effect-less code is very useful in large projects, but is there a more straightforward way to write it? For example, a straightforward idea is to mark the current state of the `Store` as read-only when entering the `Computed` code block and then restore it to writable when exiting. In read-only mode, all `set` operations are blocked.
+
+```typescript
+const counter = state(0);
+const double = computed(() => {
+  // set store to read-only
+  const result = counter.value * 2; // direct read value from counter instead of get(counter)
+  // counter.value = 4; // any write operation in read-only mode will raise an  error
+  return result;
+}); // exit computed restore store to writable
+
+double.value; // will enter read-only mode, evaluate double logic, get the result, and exit read-only mode
+```
+
+Unfortunately, this design will fail when encountering asynchronous callback functions in the current JavaScript language capabilities.
+
+```typescript
+const double = computed(async () => {
+  // set store to read-only
+  await delay(TIME_TO_DELAY);
+  // How to restore the store to read-only here?
+  // ...
+});
+```
+
+When encountering `await`, the execution of `double.value` will end, and the framework code in `Computed` can restore the `Store` to writable. If we don't do this, the subsequent set operation will raise an error. But if we do this, when `await` re-enters the `double` read function, it will not be able to restore the `Store` to read-only.
+
+Now, we are in the execution context that persists across async tasks; we hope to restore the Store's context to read-only when the async callback re-enters the `read` function. This direction has been proven to have many problems by [zone.js](https://github.com/angular/angular/tree/main/packages/zone.js). This is a dead end.
+
+So, I think the only way to implement `Computed`'s effect-less is to separate the atom and the accessor.
+
 ## Changelog & TODO
 
 [Changelog](packages/ccstate/CHANGELOG.md)