storion 0.3.0 → 0.5.0

package/README.md

@@ -315,9 +315,41 @@ export const settingsStore = store({
 
 ### Reactive Effects
 
-**The problem:** You need to sync with external systems (WebSocket, localStorage, event listeners) when state changes, and properly clean up when the state changes again or the component unmounts.
+**The problem:** You need to sync with external systems (WebSocket, localStorage) or compute derived state when dependencies change, and properly clean up when needed.
 
-**With Storion:** Effects automatically track which state properties you read and re-run only when those change. Register cleanup with `ctx.onCleanup()`.
+**With Storion:** Effects automatically track which state properties you read and re-run only when those change. Use them for side effects or computed state.
+
+**Example 1: Computed/Derived State**
+
+```ts
+import { store, effect } from "storion";
+
+export const userStore = store({
+  name: "user",
+  state: {
+    firstName: "",
+    lastName: "",
+    fullName: "", // Computed from firstName + lastName
+  },
+  setup({ state }) {
+    // Auto-updates fullName when firstName or lastName changes
+    effect(() => {
+      state.fullName = `${state.firstName} ${state.lastName}`.trim();
+    });
+
+    return {
+      setFirstName: (name: string) => {
+        state.firstName = name;
+      },
+      setLastName: (name: string) => {
+        state.lastName = name;
+      },
+    };
+  },
+});
+```
+
+**Example 2: External System Sync**
 
 ```ts
 import { store, effect } from "storion";
@@ -330,7 +362,6 @@ export const syncStore = store({
   },
   setup({ state }) {
     effect((ctx) => {
-      // Effect tracks state.userId and re-runs when it changes
       if (!state.userId) return;
 
       const ws = new WebSocket(`/ws?user=${state.userId}`);
@@ -391,23 +422,141 @@ effect((ctx) => {
 ```tsx
 import { pick } from "storion";
 
-function UserName() {
+function UserProfile() {
   // Without pick: re-renders when ANY profile property changes
   const { name } = useStore(({ get }) => {
     const [state] = get(userStore);
     return { name: state.profile.name };
   });
 
-  // With pick: re-renders ONLY when profile.name changes
-  const { name } = useStore(({ get }) => {
+  // With pick: re-renders ONLY when the picked value changes
+  // Multiple picks can be used in one selector
+  const { name, fullName, coords, settings, nested } = useStore(({ get }) => {
     const [state] = get(userStore);
-    return { name: pick(() => state.profile.name) };
+    return {
+      // Simple pick - uses default equality (===)
+      name: pick(() => state.profile.name),
+
+      // Computed value - only re-renders when result changes
+      fullName: pick(() => `${state.profile.first} ${state.profile.last}`),
+
+      // 'shallow' - compares object properties one level deep
+      coords: pick(
+        () => ({ x: state.position.x, y: state.position.y }),
+        "shallow"
+      ),
+
+      // 'deep' - recursively compares nested objects/arrays
+      settings: pick(() => state.userSettings, "deep"),
+
+      // Custom equality function - full control
+      nested: pick(
+        () => state.data.items.map((i) => i.id),
+        (a, b) => a.length === b.length && a.every((id, i) => id === b[i])
+      ),
+    };
   });
 
   return <h1>{name}</h1>;
 }
 ```
 
+### Understanding Equality: Store vs Component Level
+
+Storion provides two layers of equality control, each solving different problems:
+
+| Layer                | API               | When it runs          | Purpose                                          |
+| -------------------- | ----------------- | --------------------- | ------------------------------------------------ |
+| **Store (write)**    | `equality` option | When state is mutated | Prevent unnecessary notifications to subscribers |
+| **Component (read)** | `pick(fn, eq)`    | When selector runs    | Prevent unnecessary re-renders                   |
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Store                                                              │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │  state.coords = { x: 1, y: 2 }                               │   │
+│  │         │                                                    │   │
+│  │         ▼                                                    │   │
+│  │  equality: { coords: "shallow" }  ──► Same x,y? Skip notify  │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+│                              │                                      │
+│                    notify if changed                                │
+│                              ▼                                      │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │  Component A              │            Component B           │   │
+│  │  pick(() => coords.x)     │     pick(() => coords, "shallow")│   │
+│  │         │                 │                   │              │   │
+│  │         ▼                 │                   ▼              │   │
+│  │  Re-render if x changed   │    Re-render if x OR y changed   │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+**Example: Coordinates update**
+
+```ts
+// Store level - controls when subscribers get notified
+const mapStore = store({
+  state: { coords: { x: 0, y: 0 }, zoom: 1 },
+  equality: {
+    coords: "shallow", // Don't notify if same { x, y } values
+  },
+  setup({ state }) {
+    return {
+      setCoords: (x: number, y: number) => {
+        state.coords = { x, y }; // New object, but shallow-equal = no notify
+      },
+    };
+  },
+});
+
+// Component level - controls when THIS component re-renders
+function XCoordinate() {
+  const { x } = useStore(({ get }) => {
+    const [state] = get(mapStore);
+    return {
+      // Even if coords changed, only re-render if x specifically changed
+      x: pick(() => state.coords.x),
+    };
+  });
+  return <span>X: {x}</span>;
+}
+```
+
+### Comparison with Other Libraries
+
+| Feature            | Storion               | Redux                    | Zustand          | Jotai             | MobX            |
+| ------------------ | --------------------- | ------------------------ | ---------------- | ----------------- | --------------- |
+| **Tracking**       | Automatic             | Manual selectors         | Manual selectors | Automatic (atoms) | Automatic       |
+| **Write equality** | Per-property config   | Reducer-based            | Built-in shallow | Per-atom          | Deep by default |
+| **Read equality**  | `pick()` with options | `useSelector` + equality | `shallow` helper | Atom-level        | Computed        |
+| **Granularity**    | Property + component  | Selector-based           | Selector-based   | Atom-based        | Property-based  |
+| **Bundle size**    | ~4KB                  | ~2KB + toolkit           | ~1KB             | ~2KB              | ~15KB           |
+| **DI / Lifecycle** | Built-in container    | External (thunk/saga)    | External         | Provider-based    | External        |
+
+**Key differences:**
+
+- **Redux/Zustand**: You write selectors manually and pass equality functions to `useSelector`. Easy to forget and over-subscribe.
+
+  ```ts
+  // Zustand - must remember to add shallow
+  const coords = useStore((s) => s.coords, shallow);
+  ```
+
+- **Jotai**: Fine-grained via atoms, but requires splitting state into many atoms upfront.
+
+  ```ts
+  // Jotai - must create separate atoms
+  const xAtom = atom((get) => get(coordsAtom).x);
+  ```
+
+- **Storion**: Auto-tracking by default, `pick()` for opt-in fine-grained control, store-level equality for write optimization.
+
+  ```ts
+  // Storion - automatic tracking, pick() when you need precision
+  const x = pick(() => state.coords.x);
+  ```
+
 ### Async State Management
 
 **The problem:** Every async operation needs loading, error, and success states. You write the same boilerplate: `isLoading`, `error`, `data`, plus handling race conditions, retries, and cancellation.
@@ -494,11 +643,323 @@ function ProductList() {
 }
 ```
 
+### When to Fetch Data
+
+Storion provides multiple patterns for data fetching. Choose based on your use case:
+
+| Pattern                 | When to use                                    | Example                            |
+| ----------------------- | ---------------------------------------------- | ---------------------------------- |
+| **Setup time**          | Data needed immediately when store initializes | App config, user session           |
+| **Trigger (no deps)**   | One-time fetch when component mounts           | Initial page data                  |
+| **Trigger (with deps)** | Refetch when component visits or deps change   | Dashboard refresh                  |
+| **useEffect**           | Standard React pattern, explicit control       | Compatibility with existing code   |
+| **User interaction**    | On-demand fetching                             | Search, pagination, refresh button |
+
+```tsx
+import { store } from "storion";
+import { async, type AsyncState } from "storion/async";
+import { useStore } from "storion/react";
+import { useEffect } from "react";
+
+interface User {
+  id: string;
+  name: string;
+}
+
+export const userStore = store({
+  name: "users",
+  state: {
+    currentUser: async.fresh<User>(),
+    searchResults: async.stale<User[]>([]),
+  },
+  setup({ focus, effect }) {
+    // ═══════════════════════════════════════════════════════════════════
+    // Pattern 1: Fetch at SETUP TIME
+    // Data is fetched immediately when store is created
+    // Good for: App config, auth state, critical data
+    // ═══════════════════════════════════════════════════════════════════
+    const currentUserAsync = async(focus("currentUser"), async (ctx) => {
+      const res = await fetch("/api/me", { signal: ctx.signal });
+      return res.json();
+    });
+
+    // Fetch immediately during setup
+    currentUserAsync.dispatch();
+
+    // ═══════════════════════════════════════════════════════════════════
+    // Pattern 2: Expose DISPATCH for UI control
+    // Store provides action, UI decides when to call
+    // Good for: Search, pagination, user-triggered refresh
+    // ═══════════════════════════════════════════════════════════════════
+    const searchAsync = async(
+      focus("searchResults"),
+      async (ctx, query: string) => {
+        const res = await fetch(`/api/users/search?q=${query}`, {
+          signal: ctx.signal,
+        });
+        return res.json();
+      }
+    );
+
+    return {
+      currentUser: currentUserAsync,
+      search: searchAsync.dispatch,
+      cancelSearch: searchAsync.cancel,
+    };
+  },
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Pattern 3: TRIGGER with dependencies
+// Uses useStore's `trigger` for declarative data fetching
+// ═══════════════════════════════════════════════════════════════════════════
+
+// 3a. No deps - fetch ONCE when component mounts
+function UserProfile() {
+  const { user } = useStore(({ get, trigger }) => {
+    const [state, actions] = get(userStore);
+
+    // No deps array = fetch once, never refetch
+    trigger(actions.currentUser.dispatch, []);
+
+    return { user: state.currentUser };
+  });
+
+  if (user.status === "pending") return <Spinner />;
+  return <div>{user.data?.name}</div>;
+}
+
+// 3b. With context.id - refetch EVERY TIME component visits
+function Dashboard() {
+  const { user } = useStore(({ get, trigger, id }) => {
+    const [state, actions] = get(userStore);
+
+    // `id` changes each time component mounts = refetch on every visit
+    trigger(actions.currentUser.dispatch, [id]);
+
+    return { user: state.currentUser };
+  });
+
+  return <div>Welcome back, {user.data?.name}</div>;
+}
+
+// 3c. With custom deps - refetch when deps change
+function UserById({ userId }: { userId: string }) {
+  const { user } = useStore(
+    ({ get, trigger }) => {
+      const [state, actions] = get(userStore);
+
+      // Refetch when userId prop changes
+      trigger(() => actions.currentUser.dispatch(), [userId]);
+
+      return { user: state.currentUser };
+    },
+    [userId] // selector deps for proper tracking
+  );
+
+  return <div>{user.data?.name}</div>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Pattern 4: useEffect - standard React pattern
+// For compatibility or when you need more control
+// ═══════════════════════════════════════════════════════════════════════════
+function UserListWithEffect() {
+  const { search } = useStore(({ get }) => {
+    const [, actions] = get(userStore);
+    return { search: actions.search };
+  });
+
+  useEffect(() => {
+    search("initial");
+  }, []);
+
+  return <div>...</div>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Pattern 5: USER INTERACTION - on-demand fetching
+// ═══════════════════════════════════════════════════════════════════════════
+function SearchBox() {
+  const [query, setQuery] = useState("");
+  const { results, search, cancel } = useStore(({ get }) => {
+    const [state, actions] = get(userStore);
+    return {
+      results: state.searchResults,
+      search: actions.search,
+      cancel: actions.cancelSearch,
+    };
+  });
+
+  const handleSearch = () => {
+    cancel(); // Cancel previous search
+    search(query);
+  };
+
+  return (
+    <div>
+      <input value={query} onChange={(e) => setQuery(e.target.value)} />
+      <button onClick={handleSearch}>Search</button>
+      <button onClick={cancel}>Cancel</button>
+
+      {results.status === "pending" && <Spinner />}
+      {results.data?.map((user) => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+**Summary: Choosing the right pattern**
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  When should data be fetched?                                           │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  App starts?  ──────────►  Setup time (dispatch in setup)               │
+│                                                                         │
+│  Component mounts?                                                      │
+│       │                                                                 │
+│       ├── Once ever? ────►  trigger(fn, [])                             │
+│       │                                                                 │
+│       ├── Every visit? ──►  trigger(fn, [id])                           │
+│       │                                                                 │
+│       └── When deps change? ► trigger(fn, [dep1, dep2])                 │
+│                                                                         │
+│  User clicks? ──────────►  onClick handler calls action                 │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Suspense Pattern with `async.wait()`
+
+**The problem:** You want to use React Suspense for loading states, but managing the "throw promise" pattern manually is complex and error-prone.
+
+**With Storion:** Use `async.wait()` to extract data from async state — it throws a promise if pending (triggering Suspense) or throws the error if failed.
+
+```tsx
+import { Suspense } from "react";
+import { async } from "storion/async";
+import { useStore } from "storion/react";
+
+// Component that uses Suspense - no loading/error handling needed!
+function UserProfile() {
+  const { user } = useStore(({ get, trigger }) => {
+    const [state, actions] = get(userStore);
+
+    // Trigger fetch on mount
+    trigger(actions.fetchUser, []);
+
+    return {
+      // async.wait() throws if pending/error, returns data if success
+      user: async.wait(state.currentUser),
+    };
+  });
+
+  // This only renders when data is ready
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <p>{user.email}</p>
+    </div>
+  );
+}
+
+// Parent wraps with Suspense and ErrorBoundary
+function App() {
+  return (
+    <ErrorBoundary fallback={<div>Something went wrong</div>}>
+      <Suspense fallback={<Spinner />}>
+        <UserProfile />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+```
+
+**Multiple async states with `async.all()`:**
+
+```tsx
+function Dashboard() {
+  const { user, posts, comments } = useStore(({ get, trigger }) => {
+    const [userState, userActions] = get(userStore);
+    const [postState, postActions] = get(postStore);
+    const [commentState, commentActions] = get(commentStore);
+
+    trigger(userActions.fetch, []);
+    trigger(postActions.fetch, []);
+    trigger(commentActions.fetch, []);
+
+    // Wait for ALL async states - suspends until all are ready
+    const [user, posts, comments] = async.all(
+      userState.current,
+      postState.list,
+      commentState.recent
+    );
+
+    return { user, posts, comments };
+  });
+
+  return (
+    <div>
+      <h1>Welcome, {user.name}</h1>
+      <PostList posts={posts} />
+      <CommentList comments={comments} />
+    </div>
+  );
+}
+```
+
+**Race pattern with `async.race()`:**
+
+```tsx
+function FastestResult() {
+  const { result } = useStore(({ get, trigger }) => {
+    const [state, actions] = get(searchStore);
+
+    trigger(() => {
+      actions.searchAPI1(query);
+      actions.searchAPI2(query);
+    }, [query]);
+
+    // Returns whichever finishes first
+    return {
+      result: async.race(state.api1Results, state.api2Results),
+    };
+  });
+
+  return <ResultList items={result} />;
+}
+```
+
+**Async helpers summary:**
+
+| Helper                   | Behavior                              | Use case                  |
+| ------------------------ | ------------------------------------- | ------------------------- |
+| `async.wait(state)`      | Throws if pending/error, returns data | Single Suspense resource  |
+| `async.all(...states)`   | Waits for all, returns tuple          | Multiple parallel fetches |
+| `async.any(...states)`   | Returns first successful              | Fallback sources          |
+| `async.race(states)`     | Returns fastest                       | Competitive fetching      |
+| `async.hasData(state)`   | `boolean`                             | Check without suspending  |
+| `async.isLoading(state)` | `boolean`                             | Loading indicator         |
+| `async.isError(state)`   | `boolean`                             | Error check               |
+
 ### Dependency Injection
 
-**The problem:** Your stores need shared services (API clients, loggers, config) but you don't want to import singletons directly—it makes testing hard and creates tight coupling.
+**The problem:** Your stores need shared services (API clients, loggers, config) but importing singletons directly causes issues:
+
+- **No lifecycle management** — ES imports are forever; you can't dispose or recreate instances
+- **Testing is painful** — Mocking ES modules requires awkward workarounds
+- **No cleanup** — Resources like connections, intervals, or subscriptions leak between tests
+
+**With Storion:** The container is a full DI system that manages the complete lifecycle:
 
-**With Storion:** The container acts as a DI container. Define factory functions and resolve them with `get()`. Services are cached as singletons automatically.
+- **Automatic caching** — Services are singletons by default, created on first use
+- **Dispose & cleanup** — Call `dispose()` to clean up resources, `delete()` to remove and recreate
+- **Override for testing** — Swap implementations with `set()` without touching module imports
+- **Hierarchical containers** — Create child containers for scoped dependencies
 
 ```ts
 import { container, type Resolver } from "storion";
@@ -545,6 +1006,24 @@ const userStore = store({
     };
   },
 });
+
+// Testing - easy to mock without module mocking
+const mockApi: ApiService = {
+  get: async () => ({ id: "1", name: "Test User" }),
+  post: async () => ({}),
+};
+
+const testApp = container();
+testApp.set(createApiService, () => mockApi); // Override with mock
+
+// Now userStore will use mockApi instead of real API
+const { actions } = testApp.get(userStore);
+await actions.fetchUser("1"); // Uses mockApi.get()
+
+// Lifecycle management
+testApp.delete(createApiService); // Remove cached instance
+testApp.clear(); // Clear all cached instances
+testApp.dispose(); // Dispose container and all instances
 ```
 
 ### Middleware
@@ -555,18 +1034,24 @@ const userStore = store({
 
 ```ts
 import { container, compose, applyFor, applyExcept } from "storion";
+import type { StoreMiddleware } from "storion";
 
-// Logging middleware
-const loggingMiddleware = (spec, next) => {
-  const instance = next(spec);
-  console.log(`Store created: ${spec.name}`);
+// Logging middleware - ctx.spec is always available
+const loggingMiddleware: StoreMiddleware = (ctx) => {
+  console.log(`Creating store: ${ctx.displayName}`);
+  const instance = ctx.next();
+  console.log(`Created: ${instance.id}`);
   return instance;
 };
 
 // Persistence middleware
-const persistMiddleware = (spec, next) => {
-  const instance = next(spec);
-  // Add persistence logic...
+const persistMiddleware: StoreMiddleware = (ctx) => {
+  const instance = ctx.next();
+  // Access store-specific options directly
+  const isPersistent = ctx.spec.options.meta?.persist === true;
+  if (isPersistent) {
+    // Add persistence logic...
+  }
   return instance;
 };
 
@@ -582,7 +1067,10 @@ const app = container({
     applyFor(["authStore", "settingsStore"], loggingMiddleware),
 
     // Apply based on custom condition
-    applyFor((spec) => spec.options.meta?.persist === true, persistMiddleware)
+    applyFor(
+      (ctx) => ctx.spec.options.meta?.persist === true,
+      persistMiddleware
+    )
   ),
 });
 ```
@@ -606,7 +1094,7 @@ const app = container({
 
 ```ts
 interface StoreOptions<TState, TActions> {
-  name?: string; // Store name for debugging
+  name?: string; // Store display name for debugging (becomes spec.displayName)
   state: TState; // Initial state
   setup: (ctx: StoreContext) => TActions; // Setup function
   lifetime?: "singleton" | "autoDispose"; // Instance lifetime
@@ -616,6 +1104,42 @@ interface StoreOptions<TState, TActions> {
 }
 ```
 
+**Per-property equality** — Configure different equality checks for each state property:
+
+```ts
+const myStore = store({
+  name: "settings",
+  state: {
+    theme: "light",
+    coords: { x: 0, y: 0 },
+    items: [] as string[],
+    config: { nested: { deep: true } },
+  },
+  // Per-property equality configuration
+  equality: {
+    theme: "strict", // Default (===)
+    coords: "shallow", // Compare { x, y } properties
+    items: "shallow", // Compare array elements
+    config: "deep", // Deep recursive comparison
+  },
+  setup({ state }) {
+    return {
+      setCoords: (x: number, y: number) => {
+        // Only triggers subscribers if x or y actually changed (shallow compare)
+        state.coords = { x, y };
+      },
+    };
+  },
+});
+```
+
+| Equality            | Description                                     |
+| ------------------- | ----------------------------------------------- |
+| `"strict"`          | Default `===` comparison                        |
+| `"shallow"`         | Compares object/array properties one level deep |
+| `"deep"`            | Recursively compares nested structures          |
+| `(a, b) => boolean` | Custom comparison function                      |
+
 #### StoreContext (in setup)
 
 ```ts
@@ -686,6 +1210,71 @@ interface AsyncState<T, M extends "fresh" | "stale"> {
 }
 ```
 
+### Middleware
+
+| Export        | Description                                        |
+| ------------- | -------------------------------------------------- |
+| `compose`     | Compose multiple StoreMiddleware into one          |
+| `applyFor`    | Apply middleware conditionally (pattern/predicate) |
+| `applyExcept` | Apply middleware except for matching patterns      |
+
+#### Middleware Context (Discriminated Union)
+
+Middleware context uses a discriminated union with `type` field:
+
+```ts
+// For stores (container middleware)
+interface StoreMiddlewareContext {
+  type: "store"; // Discriminant
+  spec: StoreSpec; // Always present for stores
+  factory: Factory;
+  resolver: Resolver;
+  next: () => unknown;
+  displayName: string; // Always present for stores
+}
+
+// For plain factories (resolver middleware)
+interface FactoryMiddlewareContext {
+  type: "factory"; // Discriminant
+  factory: Factory;
+  resolver: Resolver;
+  next: () => unknown;
+  displayName: string | undefined;
+}
+
+type MiddlewareContext = FactoryMiddlewareContext | StoreMiddlewareContext;
+```
+
+**Store-specific middleware** (for containers):
+
+```ts
+// No generics needed - simple and clean
+type StoreMiddleware = (ctx: StoreMiddlewareContext) => StoreInstance;
+
+const loggingMiddleware: StoreMiddleware = (ctx) => {
+  console.log(`Creating: ${ctx.displayName}`);
+  const instance = ctx.next();
+  console.log(`Created: ${instance.id}`);
+  return instance as StoreInstance;
+};
+```
+
+**Generic middleware** (for resolver, works with both stores and factories):
+
+```ts
+type Middleware = (ctx: MiddlewareContext) => unknown;
+
+const loggingMiddleware: Middleware = (ctx) => {
+  // Use type narrowing
+  if (ctx.type === "store") {
+    console.log(`Store: ${ctx.spec.displayName}`);
+  } else {
+    console.log(`Factory: ${ctx.displayName ?? "anonymous"}`);
+  }
+  return ctx.next();
+};
+```
+
 ### Devtools (`storion/devtools`)
 
 ```ts