context-scoped-state 0.0.11 → 0.0.13

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img src="logo.svg" alt="context-scoped-state logo" width="120" height="120">
+  <img src="./logo.svg" alt="context-scoped-state logo" width="120" height="120">
   <h1>context-scoped-state</h1>
   <p><strong>State management that respects component boundaries.</strong></p>
 </div>
@@ -40,6 +40,8 @@ pnpm add context-scoped-state
 
 ### 1. Create Your Store (one file, one export)
 
+> Wondering why classes? See [API Design Choices](#api-design-choices).
+
 ```tsx
 // counterStore.ts
 import { Store, createStoreHook } from 'context-scoped-state';
@@ -51,7 +53,7 @@ class CounterStore extends Store<{ count: number }> {
 
   increment() {
     // Callback-based: receives current state, returns new state
-    this.setState(state => ({ count: state.count + 1 }));
+    this.setState((state) => ({ count: state.count + 1 }));
   }
 
   decrement() {
@@ -109,7 +111,7 @@ class UserStore extends Store<{ name: string; age: number; email: string }> {
 
   incrementAge() {
     // Callback-based: receives current state, returns partial update
-    this.patchState(state => ({ age: state.age + 1 }));
+    this.patchState((state) => ({ age: state.age + 1 }));
   }
 }
 ```
@@ -180,6 +182,45 @@ test('shows normal status when balance is healthy', () => {
 
 No mocking libraries. No global state cleanup. Just render with the state you need.
 
+### Dynamic Initial State with Context Value
+
+Pass a `value` prop to Context to provide data for `getInitialState()`. This is useful when you need to initialize store state from React props:
+
+```tsx
+type CounterState = { count: number };
+
+class CounterStore extends Store<CounterState> {
+  protected getInitialState(contextValue?: Partial<CounterState>) {
+    return { count: contextValue?.count ?? 0 };
+  }
+
+  increment() {
+    this.setState((s) => ({ count: s.count + 1 }));
+  }
+}
+
+const useCounterStore = createStoreHook(CounterStore);
+
+// Initialize store state from a React prop
+function CounterWidget({ initialCount }: { initialCount: number }) {
+  return (
+    <useCounterStore.Context value={{ count: initialCount }}>
+      <Counter />
+    </useCounterStore.Context>
+  );
+}
+
+// Now you can render multiple widgets with different starting values
+function App() {
+  return (
+    <>
+      <CounterWidget initialCount={0} />
+      <CounterWidget initialCount={100} />
+    </>
+  );
+}
+```
+
 ## Why context-scoped-state Over Other Libraries?
 
 | Feature                | context-scoped-state | Redux                        | Zustand        |
@@ -230,4 +271,118 @@ No mocking libraries. No global state cleanup. Just render with the state you ne
 
 ---
 
+## API Design Choices
+
+These design decisions are intentional trade-offs that optimize for debuggability, clarity, and simplicity.
+
+### Why Classes for Stores?
+
+Classes let us use `protected` on state-setting methods (`setState`, `patchState`). This means all state updates must go through the store class — components cannot directly modify state.
+
+**Why this matters:** When debugging, you can set a single breakpoint in your store's action methods to see exactly who is changing state and when. No more hunting through components to find where state got mutated.
+
+```tsx
+class CounterStore extends Store<{ count: number }> {
+  increment() {
+    // Set a breakpoint here to catch ALL count changes
+    this.setState((state) => ({ count: state.count + 1 }));
+  }
+}
+```
+
+### Why Can't I Destructure Actions?
+
+This won't work:
+
+```tsx
+const { increment } = useCounterStore(); // ❌ Breaks 'this' binding
+increment(); // Error: cannot read setState of undefined
+```
+
+You must use:
+
+```tsx
+const store = useCounterStore(); // ✅
+store.increment();
+```
+
+**This is a feature, not a bug.** The store is an external dependency — it should look like one. When you see `store.increment()`, it's clear you're calling a method on an external object. If you just saw `increment()`, it would look like a local function, hiding the fact that it's modifying external state.
+
+### Why `useStore.Context` Instead of Separate Exports?
+
+Instead of:
+
+```tsx
+// Two exports to manage
+export const useCounterStore = createStoreHook(CounterStore);
+export const CounterStoreContext = useCounterStore.Context;
+```
+
+We have:
+
+```tsx
+// One export does it all
+export const useCounterStore = createStoreHook(CounterStore);
+
+// Usage
+<useCounterStore.Context>
+  <App />
+</useCounterStore.Context>;
+```
+
+**Simplicity:** One export per store file. The hook and its context travel together — you can't accidentally import one without having access to the other.
+
+### Context `value` vs MockContext `state`
+
+Both `Context` and `MockContext` accept props, but they work differently:
+
+```tsx
+// Context: value is passed TO getInitialState() for computation
+<useCounterStore.Context value={{ count: 10 }}>
+
+// MockContext: state REPLACES getInitialState() entirely
+<useCounterStore.MockContext state={{ count: 10 }}>
+```
+
+**Why the distinction?**
+
+- `Context.value` — Provides input data for `getInitialState()` to use. Your `getInitialState()` method is still the single source of truth for how state is computed.
+- `MockContext.state` — Bypasses `getInitialState()` completely and sets the state directly. This is only for tests where you need to put the store in a specific state.
+
+**Debuggability:** In production code, `getInitialState()` is always called. You can set a breakpoint there to see exactly how initial state is computed. With `MockContext`, the state is set directly for test convenience.
+
+### Why `getInitialState()` Method Instead of a Property?
+
+Instead of:
+
+```tsx
+class CounterStore extends Store<{ count: number }> {
+  initialState = { count: 0 }; // Static value
+}
+```
+
+We use:
+
+```tsx
+class CounterStore extends Store<{ count: number }> {
+  protected getInitialState() {
+    // Can include logic!
+    return { count: 0 };
+  }
+}
+```
+
+**Flexibility:** A method lets you compute initial state dynamically:
+
+```tsx
+protected getInitialState() {
+  return {
+    count: parseInt(localStorage.getItem('count') ?? '0'),
+    timestamp: Date.now(),
+  };
+}
+```
+
+---
+
 **context-scoped-state** — Because not all state needs to be global.

package/dist/index.js

@@ -1,5 +1,5 @@
 import { jsx as C } from "react/jsx-runtime";
-import p, { useSyncExternalStore as H } from "react";
+import h, { useSyncExternalStore as H } from "react";
 var m = function(e, r) {
   return m = Object.setPrototypeOf || { __proto__: [] } instanceof Array && function(t, n) {
     t.__proto__ = n;
@@ -7,7 +7,7 @@ var m = function(e, r) {
     for (var o in n) Object.prototype.hasOwnProperty.call(n, o) && (t[o] = n[o]);
   }, m(e, r);
 };
-function h(e, r) {
+function v(e, r) {
   if (typeof r != "function" && r !== null)
     throw new TypeError("Class extends value " + String(r) + " is not a constructor or null");
   m(e, r);
@@ -85,8 +85,8 @@ var S = (function() {
         if (this._parentage = null, Array.isArray(s))
           try {
             for (var u = w(s), c = u.next(); !c.done; c = u.next()) {
-              var v = c.value;
-              v.remove(this);
+              var f = c.value;
+              f.remove(this);
             }
           } catch (a) {
             r = { error: a };
@@ -110,8 +110,8 @@ var S = (function() {
       if (P) {
         this._finalizers = null;
         try {
-          for (var b = w(P), f = b.next(); !f.done; f = b.next()) {
-            var V = f.value;
+          for (var b = w(P), p = b.next(); !p.done; p = b.next()) {
+            var V = p.value;
             try {
               A(V);
             } catch (a) {
@@ -122,7 +122,7 @@ var S = (function() {
           n = { error: a };
         } finally {
           try {
-            f && !f.done && (o = b.return) && o.call(b);
+            p && !p.done && (o = b.return) && o.call(b);
           } finally {
             if (n) throw n.error;
           }
@@ -169,7 +169,7 @@ function A(e) {
 }
 var $ = {
   Promise: void 0
-}, q = {
+}, W = {
   setTimeout: function(e, r) {
     for (var t = [], n = 2; n < arguments.length; n++)
       t[n - 2] = arguments[n];
@@ -180,21 +180,21 @@ var $ = {
   },
   delegate: void 0
 };
-function D(e) {
-  q.setTimeout(function() {
+function q(e) {
+  W.setTimeout(function() {
     throw e;
   });
 }
-function I() {
+function T() {
 }
 function y(e) {
   e();
 }
 var F = (function(e) {
-  h(r, e);
+  v(r, e);
   function r(t) {
     var n = e.call(this) || this;
-    return n.isStopped = !1, t ? (n.destination = t, R(t) && t.add(n)) : n.destination = K, n;
+    return n.isStopped = !1, t ? (n.destination = t, R(t) && t.add(n)) : n.destination = J, n;
   }
   return r.create = function(t, n, o) {
     return new O(t, n, o);
@@ -221,7 +221,7 @@ var F = (function(e) {
       this.unsubscribe();
     }
   }, r;
-})(S), G = (function() {
+})(S), D = (function() {
   function e(r) {
     this.partialObserver = r;
   }
@@ -253,42 +253,42 @@ var F = (function(e) {
       }
   }, e;
 })(), O = (function(e) {
-  h(r, e);
+  v(r, e);
   function r(t, n, o) {
     var i = e.call(this) || this, s;
     return l(t) || !t ? s = {
       next: t ?? void 0,
       error: n ?? void 0,
       complete: o ?? void 0
-    } : s = t, i.destination = new G(s), i;
+    } : s = t, i.destination = new D(s), i;
   }
   return r;
 })(F);
 function d(e) {
-  D(e);
+  q(e);
 }
-function J(e) {
+function G(e) {
   throw e;
 }
-var K = {
+var J = {
   closed: !0,
-  next: I,
-  error: J,
-  complete: I
-}, L = (function() {
+  next: T,
+  error: G,
+  complete: T
+}, K = (function() {
   return typeof Symbol == "function" && Symbol.observable || "@@observable";
 })();
-function Q(e) {
+function L(e) {
   return e;
 }
-function W(e) {
-  return e.length === 0 ? Q : e.length === 1 ? e[0] : function(t) {
+function Q(e) {
+  return e.length === 0 ? L : e.length === 1 ? e[0] : function(t) {
     return e.reduce(function(n, o) {
       return o(n);
     }, t);
   };
 }
-var T = (function() {
+var I = (function() {
   function e(r) {
     r && (this._subscribe = r);
   }
@@ -326,12 +326,12 @@ var T = (function() {
   }, e.prototype._subscribe = function(r) {
     var t;
     return (t = this.source) === null || t === void 0 ? void 0 : t.subscribe(r);
-  }, e.prototype[L] = function() {
+  }, e.prototype[K] = function() {
     return this;
   }, e.prototype.pipe = function() {
     for (var r = [], t = 0; t < arguments.length; t++)
       r[t] = arguments[t];
-    return W(r)(this);
+    return Q(r)(this);
   }, e.prototype.toPromise = function(r) {
     var t = this;
     return r = k(r), new r(function(n, o) {
@@ -363,7 +363,7 @@ var z = M(function(e) {
     e(this), this.name = "ObjectUnsubscribedError", this.message = "object unsubscribed";
   };
 }), B = (function(e) {
-  h(r, e);
+  v(r, e);
   function r() {
     var t = e.call(this) || this;
     return t.closed = !1, t.currentObservers = null, t.observers = [], t.isStopped = !1, t.hasError = !1, t.thrownError = null, t;
@@ -385,8 +385,8 @@ var z = M(function(e) {
             var c = u.value;
             c.next(t);
           }
-        } catch (v) {
-          o = { error: v };
+        } catch (f) {
+          o = { error: f };
         } finally {
           try {
             u && !u.done && (i = s.return) && i.call(s);
@@ -436,13 +436,13 @@ var z = M(function(e) {
     var n = this, o = n.hasError, i = n.thrownError, s = n.isStopped;
     o ? t.error(i) : s && t.complete();
   }, r.prototype.asObservable = function() {
-    var t = new T();
+    var t = new I();
     return t.source = this, t;
   }, r.create = function(t, n) {
     return new U(t, n);
   }, r;
-})(T), U = (function(e) {
-  h(r, e);
+})(I), U = (function(e) {
+  v(r, e);
   function r(t, n) {
     var o = e.call(this) || this;
     return o.destination = t, o.source = n, o;
@@ -461,7 +461,7 @@ var z = M(function(e) {
     return (o = (n = this.source) === null || n === void 0 ? void 0 : n.subscribe(t)) !== null && o !== void 0 ? o : Y;
   }, r;
 })(B), N = (function(e) {
-  h(r, e);
+  v(r, e);
   function r(t) {
     var n = e.call(this) || this;
     return n._value = t, n;
@@ -486,8 +486,10 @@ var z = M(function(e) {
 })(B);
 class et {
   _stateSubject;
-  constructor() {
-    this.state = this.getInitialState(), this._stateSubject = new N(this.getInitialState());
+  constructor(r) {
+    this._stateSubject = new N(
+      this.getInitialState(r)
+    );
   }
   getState() {
     return this._stateSubject.value;
@@ -495,7 +497,6 @@ class et {
   state$() {
     return this._stateSubject.asObservable();
   }
-  state;
   setState(r) {
     const t = typeof r == "function" ? r(this._stateSubject.value) : r;
     this._stateSubject.next(t);
@@ -506,10 +507,14 @@ class et {
   }
 }
 function nt(e) {
-  const r = p.createContext(void 0);
-  function t() {
-    const n = p.useContext(r);
-    if (!n)
+  const r = class extends e {
+    state;
+  }, t = h.createContext(
+    void 0
+  );
+  function n() {
+    const o = h.useContext(t);
+    if (!o)
       throw new Error(
         `Store hook used outside of its Context provider.
 
@@ -521,41 +526,42 @@ Then wrap your component with:
     <YourComponent />
   </useYourStore.Context>`
       );
-    const o = p.useCallback(
-      (s) => {
-        const u = n.state$().subscribe(s);
-        return () => u.unsubscribe();
+    const i = h.useCallback(
+      (u) => {
+        const c = o.state$().subscribe(u);
+        return () => c.unsubscribe();
       },
-      [n]
-    ), i = H(
-      o,
-      () => n.getState(),
-      () => n.getState()
+      [o]
+    ), s = H(
+      i,
+      () => o.getState(),
+      () => o.getState()
       // getServerSnapshot for SSR
     );
-    return n.state = i, n;
+    return o.state = s, o;
   }
-  return t.Context = function({
-    children: o
+  return n.Context = function({
+    children: i,
+    value: s
   }) {
-    const [i] = p.useState(() => new e());
-    return /* @__PURE__ */ C(r.Provider, { value: i, children: o });
-  }, t.MockContext = function({
-    children: o,
-    state: i
+    const [u] = h.useState(() => new r(s));
+    return /* @__PURE__ */ C(t.Provider, { value: u, children: i });
+  }, n.MockContext = function({
+    children: i,
+    state: s
   }) {
-    const s = () => {
-      if (i === void 0)
-        return new e();
-      class c extends e {
+    const u = () => {
+      if (s === void 0)
+        return new r();
+      const f = class extends r {
         getInitialState() {
-          return i;
+          return s;
         }
-      }
-      return new c();
-    }, u = p.useRef(s());
-    return /* @__PURE__ */ C(r.Provider, { value: u.current, children: o });
-  }, t;
+      };
+      return new f();
+    }, c = h.useRef(u());
+    return /* @__PURE__ */ C(t.Provider, { value: c.current, children: i });
+  }, n;
 }
 export {
   et as Store,

package/dist/lib/Store.d.ts

@@ -1,10 +1,9 @@
-declare abstract class Store<T> {
-    protected abstract getInitialState(): T;
+declare abstract class Store<T, C = Partial<T>> {
+    protected abstract getInitialState(contextValue?: C): T;
     private readonly _stateSubject;
-    constructor();
+    constructor(contextValue?: C);
     getState(): T;
     state$(): import('rxjs').Observable<T>;
-    state: T;
     protected setState(newState: T | ((currentState: T) => T)): void;
     protected patchState(partialState: Partial<T> | ((currentState: T) => Partial<T>)): void;
 }

package/dist/lib/Store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Store.d.ts","sourceRoot":"","sources":["../../src/lib/Store.ts"],"names":[],"mappings":"AAEA,uBAAe,KAAK,CAAC,CAAC;IACpB,SAAS,CAAC,QAAQ,CAAC,eAAe,IAAI,CAAC;IAEvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;;IAOnD,QAAQ,IAAI,CAAC;IAIb,MAAM;IAIC,KAAK,EAAE,CAAC,CAAC;IAEhB,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI;IAQhE,SAAS,CAAC,UAAU,CAClB,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,GAC3D,IAAI;CAQR;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}
+{"version":3,"file":"Store.d.ts","sourceRoot":"","sources":["../../src/lib/Store.ts"],"names":[],"mappings":"AAEA,uBAAe,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IACpC,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC;IAEvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAEvC,YAAY,CAAC,EAAE,CAAC;IAM5B,QAAQ,IAAI,CAAC;IAIb,MAAM;IAIN,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI;IAQhE,SAAS,CAAC,UAAU,CAClB,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,GAC3D,IAAI;CAQR;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/dist/lib/createStore.d.ts

@@ -1,9 +1,12 @@
 import { default as React } from 'react';
 import { Store } from './Store';
-declare function createStoreHook<T extends Store<any>>(storeClass: new () => T): {
-    (): T;
-    Context({ children, }: {
+declare function createStoreHook<T extends Store<any, any>>(storeClass: new (contextValue?: any) => T): {
+    (): T & {
+        readonly state: ReturnType<T["getState"]>;
+    };
+    Context({ children, value, }: {
         children: React.ReactNode;
+        value?: T extends Store<any, infer C> ? C : never;
     }): import("react/jsx-runtime").JSX.Element;
     MockContext({ children, state, }: {
         children: React.ReactNode;

package/dist/lib/createStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createStore.d.ts","sourceRoot":"","sources":["../../src/lib/createStore.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA+B,MAAM,OAAO,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,iBAAS,eAAe,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC;QAG/C,CAAC;2BAoCnB;QACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;KAC3B;sCAWE;QACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;QAC1B,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;KACnC;EAuBF;AACD,OAAO,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"createStore.d.ts","sourceRoot":"","sources":["../../src/lib/createStore.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA+B,MAAM,OAAO,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,iBAAS,eAAe,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,EAChD,UAAU,EAAE,KAAK,YAAY,CAAC,EAAE,GAAG,KAAK,CAAC;;;;kCAyDtC;QACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;QAC1B,KAAK,CAAC,6BAvD2C,CAAC,cAuDzB;KAC1B;sCAWE;QACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;QAC1B,KAAK,CAAC,4BAAY;KACnB;EAwBF;AACD,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-scoped-state",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "license": "MIT",
   "type": "module",
   "repository": {