context-scoped-state 0.0.13 → 0.0.14

package/README.md

@@ -221,6 +221,38 @@ function App() {
 }
 ```
 
+### Optional Store Access
+
+Sometimes a component needs to work both inside and outside a store provider. Instead of throwing an error, `useStore.optional()` returns `undefined` when no provider is found:
+
+```tsx
+function UserName({ userId }: { userId: string }) {
+  const store = useUserStore.optional();
+
+  if (!store) {
+    return <span>{userId}</span>;
+  }
+
+  return <span>{store.state.users.get(userId) ?? userId}</span>;
+}
+
+// Works inside a provider — shows resolved user name
+function Dashboard() {
+  return (
+    <useUserStore.Context>
+      <UserName userId="42" />
+    </useUserStore.Context>
+  );
+}
+
+// Also works without a provider — falls back to showing the raw ID
+function SimpleList() {
+  return <UserName userId="42" />;
+}
+```
+
+This is useful for shared components that are rendered in different parts of your app, where a provider may or may not be present.
+
 ## Why context-scoped-state Over Other Libraries?
 
 | Feature                | context-scoped-state | Redux                        | Zustand        |
@@ -351,6 +383,24 @@ Both `Context` and `MockContext` accept props, but they work differently:
 
 **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.
 
+### `useStore()` vs `useStore.optional()`
+
+By default, calling the hook outside a provider throws an error:
+
+```tsx
+const store = useCounterStore(); // Throws if no <useCounterStore.Context> above
+```
+
+This is intentional — it catches missing providers early during development. Most components _require_ the store to function, so a loud failure is better than a silent `undefined`.
+
+For components that genuinely need to work with or without a provider, use `.optional()`:
+
+```tsx
+const store = useCounterStore.optional(); // Returns undefined if no provider
+```
+
+**Why two variants instead of a config flag?** Type safety. `useStore()` returns `TWithState` — you can use the store directly without null checks. `useStore.optional()` returns `TWithState | undefined` — TypeScript forces you to handle the `undefined` case. This keeps the common path clean while making the optional path explicitly safe.
+
 ### Why `getInitialState()` Method Instead of a Property?
 
 Instead of:

package/dist/index.js

@@ -1,22 +1,22 @@
 import { jsx as C } from "react/jsx-runtime";
-import h, { useSyncExternalStore as H } from "react";
-var m = function(e, r) {
-  return m = Object.setPrototypeOf || { __proto__: [] } instanceof Array && function(t, n) {
+import f, { useSyncExternalStore as $ } from "react";
+var w = function(e, r) {
+  return w = Object.setPrototypeOf || { __proto__: [] } instanceof Array && function(t, n) {
     t.__proto__ = n;
   } || function(t, n) {
     for (var o in n) Object.prototype.hasOwnProperty.call(n, o) && (t[o] = n[o]);
-  }, m(e, r);
+  }, w(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);
+  w(e, r);
   function t() {
     this.constructor = e;
   }
   e.prototype = r === null ? Object.create(r) : (t.prototype = r.prototype, new t());
 }
-function w(e) {
+function E(e) {
   var r = typeof Symbol == "function" && Symbol.iterator, t = r && e[r], n = 0;
   if (t) return t.call(e);
   if (e && typeof e.length == "number") return {
@@ -26,7 +26,7 @@ function w(e) {
   };
   throw new TypeError(r ? "Object is not iterable." : "Symbol.iterator is not defined.");
 }
-function x(e, r) {
+function g(e, r) {
   var t = typeof Symbol == "function" && e[Symbol.iterator];
   if (!t) return e;
   var n = t.call(e), o, i = [], s;
@@ -43,7 +43,7 @@ function x(e, r) {
   }
   return i;
 }
-function E(e, r, t) {
+function x(e, r, t) {
   if (t || arguments.length === 2) for (var n = 0, o = r.length, i; n < o; n++)
     (i || !(n in r)) && (i || (i = Array.prototype.slice.call(r, 0, n)), i[n] = r[n]);
   return e.concat(i || Array.prototype.slice.call(r));
@@ -57,7 +57,7 @@ function M(e) {
   }, t = e(r);
   return t.prototype = Object.create(Error.prototype), t.prototype.constructor = t, t;
 }
-var _ = M(function(e) {
+var m = M(function(e) {
   return function(t) {
     e(this), this.message = t ? t.length + ` errors occurred during unsubscription:
 ` + t.map(function(n, o) {
@@ -66,13 +66,13 @@ var _ = M(function(e) {
   `) : "", this.name = "UnsubscriptionError", this.errors = t;
   };
 });
-function g(e, r) {
+function O(e, r) {
   if (e) {
     var t = e.indexOf(r);
     0 <= t && e.splice(t, 1);
   }
 }
-var S = (function() {
+var _ = (function() {
   function e(r) {
     this.initialTeardown = r, this.closed = !1, this._parentage = null, this._finalizers = null;
   }
@@ -84,9 +84,9 @@ var S = (function() {
       if (s)
         if (this._parentage = null, Array.isArray(s))
           try {
-            for (var u = w(s), c = u.next(); !c.done; c = u.next()) {
-              var f = c.value;
-              f.remove(this);
+            for (var u = E(s), c = u.next(); !c.done; c = u.next()) {
+              var p = c.value;
+              p.remove(this);
             }
           } catch (a) {
             r = { error: a };
@@ -99,37 +99,37 @@ var S = (function() {
           }
         else
           s.remove(this);
-      var j = this.initialTeardown;
-      if (l(j))
+      var b = this.initialTeardown;
+      if (l(b))
         try {
-          j();
+          b();
         } catch (a) {
-          i = a instanceof _ ? a.errors : [a];
+          i = a instanceof m ? a.errors : [a];
         }
       var P = this._finalizers;
       if (P) {
         this._finalizers = null;
         try {
-          for (var b = w(P), p = b.next(); !p.done; p = b.next()) {
-            var V = p.value;
+          for (var d = E(P), h = d.next(); !h.done; h = d.next()) {
+            var H = h.value;
             try {
-              A(V);
+              A(H);
             } catch (a) {
-              i = i ?? [], a instanceof _ ? i = E(E([], x(i)), x(a.errors)) : i.push(a);
+              i = i ?? [], a instanceof m ? i = x(x([], g(i)), g(a.errors)) : i.push(a);
             }
           }
         } catch (a) {
           n = { error: a };
         } finally {
           try {
-            p && !p.done && (o = b.return) && o.call(b);
+            h && !h.done && (o = d.return) && o.call(d);
           } finally {
             if (n) throw n.error;
           }
         }
       }
       if (i)
-        throw new _(i);
+        throw new m(i);
     }
   }, e.prototype.add = function(r) {
     var t;
@@ -152,52 +152,52 @@ var S = (function() {
     this._parentage = Array.isArray(t) ? (t.push(r), t) : t ? [t, r] : r;
   }, e.prototype._removeParent = function(r) {
     var t = this._parentage;
-    t === r ? this._parentage = null : Array.isArray(t) && g(t, r);
+    t === r ? this._parentage = null : Array.isArray(t) && O(t, r);
   }, e.prototype.remove = function(r) {
     var t = this._finalizers;
-    t && g(t, r), r instanceof e && r._removeParent(this);
+    t && O(t, r), r instanceof e && r._removeParent(this);
   }, e.EMPTY = (function() {
     var r = new e();
     return r.closed = !0, r;
   })(), e;
-})(), Y = S.EMPTY;
+})(), Y = _.EMPTY;
 function R(e) {
-  return e instanceof S || e && "closed" in e && l(e.remove) && l(e.add) && l(e.unsubscribe);
+  return e instanceof _ || e && "closed" in e && l(e.remove) && l(e.add) && l(e.unsubscribe);
 }
 function A(e) {
   l(e) ? e() : e.unsubscribe();
 }
-var $ = {
+var W = {
   Promise: void 0
-}, W = {
+}, q = {
   setTimeout: function(e, r) {
     for (var t = [], n = 2; n < arguments.length; n++)
       t[n - 2] = arguments[n];
-    return setTimeout.apply(void 0, E([e, r], x(t)));
+    return setTimeout.apply(void 0, x([e, r], g(t)));
   },
   clearTimeout: function(e) {
     return clearTimeout(e);
   },
   delegate: void 0
 };
-function q(e) {
-  W.setTimeout(function() {
+function D(e) {
+  q.setTimeout(function() {
     throw e;
   });
 }
 function T() {
 }
-function y(e) {
+function S(e) {
   e();
 }
 var F = (function(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 = J, n;
+    return n.isStopped = !1, t ? (n.destination = t, R(t) && t.add(n)) : n.destination = K, n;
   }
   return r.create = function(t, n, o) {
-    return new O(t, n, o);
+    return new j(t, n, o);
   }, r.prototype.next = function(t) {
     this.isStopped || this._next(t);
   }, r.prototype.error = function(t) {
@@ -221,7 +221,7 @@ var F = (function(e) {
       this.unsubscribe();
     }
   }, r;
-})(S), D = (function() {
+})(_), G = (function() {
   function e(r) {
     this.partialObserver = r;
   }
@@ -231,7 +231,7 @@ var F = (function(e) {
       try {
         t.next(r);
       } catch (n) {
-        d(n);
+        y(n);
       }
   }, e.prototype.error = function(r) {
     var t = this.partialObserver;
@@ -239,20 +239,20 @@ var F = (function(e) {
       try {
         t.error(r);
       } catch (n) {
-        d(n);
+        y(n);
       }
     else
-      d(r);
+      y(r);
   }, e.prototype.complete = function() {
     var r = this.partialObserver;
     if (r.complete)
       try {
         r.complete();
       } catch (t) {
-        d(t);
+        y(t);
       }
   }, e;
-})(), O = (function(e) {
+})(), j = (function(e) {
   v(r, e);
   function r(t, n, o) {
     var i = e.call(this) || this, s;
@@ -260,29 +260,29 @@ var F = (function(e) {
       next: t ?? void 0,
       error: n ?? void 0,
       complete: o ?? void 0
-    } : s = t, i.destination = new D(s), i;
+    } : s = t, i.destination = new G(s), i;
   }
   return r;
 })(F);
-function d(e) {
-  q(e);
+function y(e) {
+  D(e);
 }
-function G(e) {
+function J(e) {
   throw e;
 }
-var J = {
+var K = {
   closed: !0,
   next: T,
-  error: G,
+  error: J,
   complete: T
-}, K = (function() {
+}, L = (function() {
   return typeof Symbol == "function" && Symbol.observable || "@@observable";
 })();
-function L(e) {
+function Q(e) {
   return e;
 }
-function Q(e) {
-  return e.length === 0 ? L : e.length === 1 ? e[0] : function(t) {
+function X(e) {
+  return e.length === 0 ? Q : e.length === 1 ? e[0] : function(t) {
     return e.reduce(function(n, o) {
       return o(n);
     }, t);
@@ -296,8 +296,8 @@ var I = (function() {
     var t = new e();
     return t.source = this, t.operator = r, t;
   }, e.prototype.subscribe = function(r, t, n) {
-    var o = this, i = Z(r) ? r : new O(r, t, n);
-    return y(function() {
+    var o = this, i = z(r) ? r : new j(r, t, n);
+    return S(function() {
       var s = o, u = s.operator, c = s.source;
       i.add(u ? u.call(i, c) : c ? o._subscribe(i) : o._trySubscribe(i));
     }), i;
@@ -310,7 +310,7 @@ var I = (function() {
   }, e.prototype.forEach = function(r, t) {
     var n = this;
     return t = k(t), new t(function(o, i) {
-      var s = new O({
+      var s = new j({
         next: function(u) {
           try {
             r(u);
@@ -326,12 +326,12 @@ var I = (function() {
   }, e.prototype._subscribe = function(r) {
     var t;
     return (t = this.source) === null || t === void 0 ? void 0 : t.subscribe(r);
-  }, e.prototype[K] = function() {
+  }, e.prototype[L] = function() {
     return this;
   }, e.prototype.pipe = function() {
     for (var r = [], t = 0; t < arguments.length; t++)
       r[t] = arguments[t];
-    return Q(r)(this);
+    return X(r)(this);
   }, e.prototype.toPromise = function(r) {
     var t = this;
     return r = k(r), new r(function(n, o) {
@@ -350,15 +350,15 @@ var I = (function() {
 })();
 function k(e) {
   var r;
-  return (r = e ?? $.Promise) !== null && r !== void 0 ? r : Promise;
+  return (r = e ?? W.Promise) !== null && r !== void 0 ? r : Promise;
 }
-function X(e) {
+function Z(e) {
   return e && l(e.next) && l(e.error) && l(e.complete);
 }
-function Z(e) {
-  return e && e instanceof F || X(e) && R(e);
+function z(e) {
+  return e && e instanceof F || Z(e) && R(e);
 }
-var z = M(function(e) {
+var V = M(function(e) {
   return function() {
     e(this), this.name = "ObjectUnsubscribedError", this.message = "object unsubscribed";
   };
@@ -373,20 +373,20 @@ var z = M(function(e) {
     return n.operator = t, n;
   }, r.prototype._throwIfClosed = function() {
     if (this.closed)
-      throw new z();
+      throw new V();
   }, r.prototype.next = function(t) {
     var n = this;
-    y(function() {
+    S(function() {
       var o, i;
       if (n._throwIfClosed(), !n.isStopped) {
         n.currentObservers || (n.currentObservers = Array.from(n.observers));
         try {
-          for (var s = w(n.currentObservers), u = s.next(); !u.done; u = s.next()) {
+          for (var s = E(n.currentObservers), u = s.next(); !u.done; u = s.next()) {
             var c = u.value;
             c.next(t);
           }
-        } catch (f) {
-          o = { error: f };
+        } catch (p) {
+          o = { error: p };
         } finally {
           try {
             u && !u.done && (i = s.return) && i.call(s);
@@ -398,7 +398,7 @@ var z = M(function(e) {
     });
   }, r.prototype.error = function(t) {
     var n = this;
-    y(function() {
+    S(function() {
       if (n._throwIfClosed(), !n.isStopped) {
         n.hasError = n.isStopped = !0, n.thrownError = t;
         for (var o = n.observers; o.length; )
@@ -407,7 +407,7 @@ var z = M(function(e) {
     });
   }, r.prototype.complete = function() {
     var t = this;
-    y(function() {
+    S(function() {
       if (t._throwIfClosed(), !t.isStopped) {
         t.isStopped = !0;
         for (var n = t.observers; n.length; )
@@ -429,8 +429,8 @@ var z = M(function(e) {
     return this._throwIfClosed(), this._checkFinalizedStatuses(t), this._innerSubscribe(t);
   }, r.prototype._innerSubscribe = function(t) {
     var n = this, o = this, i = o.hasError, s = o.isStopped, u = o.observers;
-    return i || s ? Y : (this.currentObservers = null, u.push(t), new S(function() {
-      n.currentObservers = null, g(u, t);
+    return i || s ? Y : (this.currentObservers = null, u.push(t), new _(function() {
+      n.currentObservers = null, O(u, t);
     }));
   }, r.prototype._checkFinalizedStatuses = function(t) {
     var n = this, o = n.hasError, i = n.thrownError, s = n.isStopped;
@@ -509,12 +509,29 @@ class et {
 function nt(e) {
   const r = class extends e {
     state;
-  }, t = h.createContext(
+  }, t = f.createContext(
     void 0
   );
-  function n() {
-    const o = h.useContext(t);
-    if (!o)
+  function n(i) {
+    const s = f.useCallback(
+      (u) => {
+        if (!i) return () => {
+        };
+        const c = i.state$().subscribe(u);
+        return () => c.unsubscribe();
+      },
+      [i]
+    );
+    if ($(
+      s,
+      () => i?.getState(),
+      () => i?.getState()
+    ), !!i)
+      return i.state = i.getState(), i;
+  }
+  function o() {
+    const i = f.useContext(t), s = n(i);
+    if (!s)
       throw new Error(
         `Store hook used outside of its Context provider.
 
@@ -526,42 +543,33 @@ Then wrap your component with:
     <YourComponent />
   </useYourStore.Context>`
       );
-    const i = h.useCallback(
-      (u) => {
-        const c = o.state$().subscribe(u);
-        return () => c.unsubscribe();
-      },
-      [o]
-    ), s = H(
-      i,
-      () => o.getState(),
-      () => o.getState()
-      // getServerSnapshot for SSR
-    );
-    return o.state = s, o;
+    return s;
   }
-  return n.Context = function({
-    children: i,
-    value: s
+  return o.optional = function() {
+    const s = f.useContext(t);
+    return n(s);
+  }, o.Context = function({
+    children: s,
+    value: u
   }) {
-    const [u] = h.useState(() => new r(s));
-    return /* @__PURE__ */ C(t.Provider, { value: u, children: i });
-  }, n.MockContext = function({
-    children: i,
-    state: s
+    const [c] = f.useState(() => new r(u));
+    return /* @__PURE__ */ C(t.Provider, { value: c, children: s });
+  }, o.MockContext = function({
+    children: s,
+    state: u
   }) {
-    const u = () => {
-      if (s === void 0)
+    const c = () => {
+      if (u === void 0)
         return new r();
-      const f = class extends r {
+      const b = class extends r {
         getInitialState() {
-          return s;
+          return u;
         }
       };
-      return new f();
-    }, c = h.useRef(u());
-    return /* @__PURE__ */ C(t.Provider, { value: c.current, children: i });
-  }, n;
+      return new b();
+    }, p = f.useRef(c());
+    return /* @__PURE__ */ C(t.Provider, { value: p.current, children: s });
+  }, o;
 }
 export {
   et as Store,

package/dist/lib/createStore.d.ts

@@ -4,6 +4,9 @@ declare function createStoreHook<T extends Store<any, any>>(storeClass: new (con
     (): T & {
         readonly state: ReturnType<T["getState"]>;
     };
+    optional(): (T & {
+        readonly state: ReturnType<T["getState"]>;
+    }) | undefined;
     Context({ children, value, }: {
         children: React.ReactNode;
         value?: T extends Store<any, infer C> ? C : never;

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,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"}
+{"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;;;;gBAgEQ;;SAAa,SAAS;kCAQpE;QACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;QAC1B,KAAK,CAAC,6BAtE2C,CAAC,cAsEzB;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.13",
+  "version": "0.0.14",
   "license": "MIT",
   "type": "module",
   "repository": {