storion 0.4.0 → 0.6.0

package/README.md

@@ -282,9 +282,7 @@ export const settingsStore = store({
 
     return {
       // Direct value
-      setTheme: (theme: "light" | "dark") => {
-        setTheme(theme);
-      },
+      setTheme,
 
       // Reducer - returns new value
       toggleTheme: () => {
@@ -422,23 +420,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.
@@ -525,11 +641,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:
 
-**With Storion:** The container acts as a DI container. Define factory functions and resolve them with `get()`. Services are cached as singletons automatically.
+- **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:
+
+- **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";
@@ -576,8 +1004,92 @@ 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
 ```
 
+### Parameterized Factories with `create()`
+
+**The problem:** Some services need configuration at creation time (database connections, loggers with namespaces, API clients with different endpoints). But `get()` only works with parameterless factories since it caches instances.
+
+**With Storion:** Use `create()` for parameterized factories. Unlike `get()`, `create()` always returns fresh instances and supports additional arguments.
+
+```ts
+import { store, container, type Resolver } from "storion";
+
+// Parameterized factory - receives resolver + custom args
+function createLogger(resolver: Resolver, namespace: string) {
+  return {
+    info: (msg: string) => console.log(`[${namespace}] INFO: ${msg}`),
+    error: (msg: string) => console.error(`[${namespace}] ERROR: ${msg}`),
+  };
+}
+
+function createDatabase(
+  resolver: Resolver,
+  config: { host: string; port: number }
+) {
+  return {
+    query: (sql: string) =>
+      fetch(`http://${config.host}:${config.port}/query`, {
+        method: "POST",
+        body: sql,
+      }),
+    close: () => {
+      /* cleanup */
+    },
+  };
+}
+
+// Use in store setup
+const userStore = store({
+  name: "user",
+  state: { users: [] as User[] },
+  setup({ create }) {
+    // Each call creates a fresh instance with specific config
+    const logger = create(createLogger, "user-store");
+    const db = create(createDatabase, { host: "localhost", port: 5432 });
+
+    return {
+      fetchUsers: async () => {
+        logger.info("Fetching users...");
+        await db.query("SELECT * FROM users");
+      },
+    };
+  },
+});
+
+// Also works with container directly
+const app = container();
+const authLogger = app.create(createLogger, "auth");
+const adminDb = app.create(createDatabase, { host: "admin.db", port: 5433 });
+```
+
+**Key differences between `get()` and `create()`:**
+
+| Feature    | `get()`                     | `create()`                                    |
+| ---------- | --------------------------- | --------------------------------------------- |
+| Caching    | Yes (singleton per factory) | No (always fresh)                             |
+| Arguments  | None (parameterless only)   | Supports additional arguments                 |
+| Use case   | Shared services             | Configured instances, child stores            |
+| Middleware | Applied                     | Applied (without args) / Bypassed (with args) |
+
 ### Middleware
 
 **The problem:** You need cross-cutting behavior (logging, persistence, devtools) applied to some or all stores, without modifying each store individually.
@@ -656,13 +1168,52 @@ 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
 interface StoreContext<TState, TActions> {
   state: TState; // First-level props only (state.x = y)
-  get<T>(spec: StoreSpec<T>): StoreTuple; // Get dependency store
-  get<T>(factory: Factory<T>): T; // Get DI service
+  get<T>(spec: StoreSpec<T>): StoreTuple; // Get dependency store (cached)
+  get<T>(factory: Factory<T>): T; // Get DI service (cached)
+  create<T>(spec: StoreSpec<T>): StoreInstance<T>; // Create child store (fresh)
+  create<T>(factory: Factory<T>): T; // Create service (fresh)
+  create<R, A>(factory: (r, ...a: A) => R, ...a: A): R; // Parameterized factory
   focus<P extends Path>(path: P): Focus; // Lens-like accessor
   update(fn: (draft: TState) => void): void; // For nested/array mutations
   dirty(prop?: keyof TState): boolean; // Check if state changed
@@ -673,6 +1224,29 @@ interface StoreContext<TState, TActions> {
 
 > **Note:** `state` allows direct assignment only for first-level properties. Use `update()` for nested objects, arrays, or batch updates.
 
+**`get()` vs `create()` — When to use each:**
+
+| Method     | Caching  | Use case                                               |
+| ---------- | -------- | ------------------------------------------------------ |
+| `get()`    | Cached   | Shared dependencies, singleton services                |
+| `create()` | No cache | Child stores, parameterized factories, fresh instances |
+
+```ts
+setup({ get, create }) {
+  // get() - cached, same instance every time
+  const api = get(apiService); // Singleton
+
+  // create() - fresh instance each call
+  const childStore = create(childSpec); // New store instance
+
+  // create() with arguments - parameterized factory
+  const db = create(createDatabase, { host: 'localhost', port: 5432 });
+  const logger = create(createLogger, 'auth-store');
+
+  return { /* ... */ };
+}
+```
+
 ### React (`storion/react`)
 
 | Export                     | Description                               |
@@ -687,10 +1261,13 @@ interface StoreContext<TState, TActions> {
 #### useStore Selector
 
 ```ts
-// Selector receives context with get() for accessing stores
-const result = useStore(({ get, mixin, once }) => {
+// Selector receives context with get(), create(), mixin(), once()
+const result = useStore(({ get, create, mixin, once }) => {
   const [state, actions] = get(myStore);
-  const service = get(myFactory);
+  const service = get(myFactory); // Cached
+
+  // create() for parameterized factories (fresh instance each render)
+  const logger = create(createLogger, "my-component");
 
   // Run once on mount
   once(() => actions.init());
@@ -734,34 +1311,61 @@ interface AsyncState<T, M extends "fresh" | "stale"> {
 | `applyFor`    | Apply middleware conditionally (pattern/predicate) |
 | `applyExcept` | Apply middleware except for matching patterns      |
 
-#### StoreMiddlewareContext
+#### Middleware Context (Discriminated Union)
 
-Container middleware uses `StoreMiddlewareContext` where `spec` is always available:
+Middleware context uses a discriminated union with `type` field:
 
 ```ts
-interface StoreMiddlewareContext<S, A> {
-  spec: StoreSpec<S, A>; // The store spec (always present)
-  resolver: Resolver; // The resolver/container instance
-  next: () => StoreInstance<S, A>; // Call next middleware or create the store
-  displayName: string; // Store name (always present for stores)
+// 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 StoreMiddleware = <S, A>(
-  ctx: StoreMiddlewareContext<S, A>
-) => StoreInstance<S, A>;
+type MiddlewareContext = FactoryMiddlewareContext | StoreMiddlewareContext;
 ```
 
-For generic resolver middleware (non-container), use `Middleware` with `MiddlewareContext`:
+**Store-specific middleware** (for containers):
 
 ```ts
-interface MiddlewareContext<T> {
-  factory: Factory<T>; // The factory being invoked
-  resolver: Resolver; // The resolver instance
-  next: () => T; // Call next middleware or the factory
-  displayName?: string; // Name (from factory.displayName or factory.name)
-}
+// 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):
 
-type Middleware = <T>(ctx: MiddlewareContext<T>) => T;
+```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`)