react-reactive-val 2.0.4 → 2.1.0

package/README.md

@@ -11,6 +11,7 @@ A lightweight, type-safe reactive value management library for React application
 - 📦 **Tree-shakeable**: Only import what you need
 - 🌳 **Multiple formats**: Supports ESM, CommonJS, and UMD
 - 🌟 **Context Support**: Share reactive values efficiently through React Context
+- 🎭 **Side Effects**: Register callbacks to run when values change
 
 ## Installation
 
@@ -41,6 +42,42 @@ function Counter() {
 }
 ```
 
+### Side Effects (New in v2.1.0)
+
+You can register side effects to run whenever a reactive value changes:
+
+```tsx
+import { reallyReactiveVal, useReactiveEffect } from 'react-reactive-val';
+
+// Create a shared reactive value
+const [count, CountProvider] = reallyReactiveVal(0);
+
+// Register an effect directly
+const cleanup = count.effect(value => {
+  console.log(`Count changed to: ${value}`);
+  // Optional cleanup function
+  return () => console.log('Cleaning up previous effect');
+});
+
+// Later, you can clean up the effect
+cleanup();
+
+// Or use the hook in components for automatic cleanup
+function CounterWithEffect() {
+  useReactiveEffect(count, value => {
+    console.log(`Count in component is: ${value}`);
+    return () => console.log('Component effect cleanup');
+  });
+
+  return (
+    <div>
+      <p>Count: {count()}</p>
+      <button onClick={() => count(prev => prev + 1)}>Increment</button>
+    </div>
+  );
+}
+```
+
 ### Sharing State Between Components
 
 #### Using Direct Reference
@@ -65,7 +102,7 @@ function CounterButtons() {
 }
 ```
 
-#### Using Context (New in v2)
+#### Using Context
 
 ```tsx
 import { reallyReactiveVal } from 'react-reactive-val';
@@ -113,7 +150,7 @@ const value = useReactiveValue(initialValue);
 
 ### `reallyReactiveVal<T>(initialValue: T)`
 
-Creates a standalone reactive value that can be used across components. In v2, it returns a tuple containing the reactive value function, a Context Provider component, and a custom hook for accessing the value through context.
+Creates a standalone reactive value that can be used across components. Returns a tuple containing the reactive value function, a Context Provider component, and a custom hook for accessing the value through context.
 
 ```tsx
 const [value, Provider, useValue] = reallyReactiveVal(initialValue);
@@ -121,10 +158,27 @@ const [value, Provider, useValue] = reallyReactiveVal(initialValue);
 
 - `initialValue`: The initial value of the reactive state
 - Returns: A tuple containing:
-  1. A function that can both read and update the value
+  1. A function that can both read and update the value, with an additional `effect` method
   2. A Context Provider component for wrapping consumers
   3. A custom hook for accessing the value within the Context
 
+### `useReactiveEffect<T>(reactiveValue: FnType<T>, callback: EffectCallback<T>)`
+
+A React hook for managing side effects with reactive values.
+
+```tsx
+useReactiveEffect(value, newValue => {
+  console.log(`Value changed to: ${newValue}`);
+  return () => {
+    // Optional cleanup
+  };
+});
+```
+
+- `reactiveValue`: The reactive value to watch
+- `callback`: Function to run when the value changes
+- The callback can optionally return a cleanup function
+
 ### Usage with Value Getter/Setter
 
 ```tsx
@@ -136,6 +190,14 @@ value(newValue);
 
 // Update based on previous value
 value(prev => computeNewValue(prev));
+
+// Register a side effect
+const cleanup = value.effect(newValue => {
+  console.log(`Value changed to: ${newValue}`);
+  return () => {
+    // Optional cleanup
+  };
+});
 ```
 
 ## TypeScript Support
@@ -154,6 +216,14 @@ user(prev => ({ ...prev, name: 'John' })); // Type safe!
 
 // With Context
 const [userValue, UserProvider, useUser] = reallyReactiveVal<User | null>(null);
+
+// With Effects
+userValue.effect(user => {
+  console.log(`User updated: ${user?.name}`);
+  return () => {
+    // Cleanup is properly typed
+  };
+});
 ```
 
 ## Contributing

package/dist/index.cjs.js

@@ -1,2 +1,2 @@
 /*! For license information please see index.cjs.js.LICENSE.txt */
-(()=>{"use strict";var e={698:(e,r)=>{var t=Symbol.for("react.transitional.element");function n(e,r,n){var o=null;if(void 0!==n&&(o=""+n),void 0!==r.key&&(o=""+r.key),"key"in r)for(var u in n={},r)"key"!==u&&(n[u]=r[u]);else n=r;return r=n.ref,{$$typeof:t,type:e,key:o,ref:void 0!==r?r:null,props:n}}Symbol.for("react.fragment"),r.jsx=n},848:(e,r,t)=>{e.exports=t(698)}},r={};function t(n){var o=r[n];if(void 0!==o)return o.exports;var u=r[n]={exports:{}};return e[n](u,u.exports,t),u.exports}t.d=(e,r)=>{for(var n in r)t.o(r,n)&&!t.o(e,n)&&Object.defineProperty(e,n,{enumerable:!0,get:r[n]})},t.o=(e,r)=>Object.prototype.hasOwnProperty.call(e,r),t.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var n={};t.r(n),t.d(n,{Context:()=>a,default:()=>i,reallyReactiveVal:()=>l,useReactiveValueContext:()=>f});const o=require("react");var u=t(848);function i(e){return(0,o.useMemo)((function(){return l(e)}),[e])}var a=(0,o.createContext)(null),f=function(){return(0,o.useContext)(a)},l=function(e){var r=e,t=new Set,n=(0,o.memo)((function(){return(0,o.useSyncExternalStore)((function(e){return t.add(e),function(){return t.delete(e)}}),(function(){return r}))}));function i(e){if(void 0===e)return(0,u.jsx)(n,{});r="function"==typeof e?e(r):e,t.forEach((function(e){e()}))}return[i,(0,o.memo)((function(e){var r=e.children;return(0,u.jsx)(a.Provider,{value:i,children:r})}))]};module.exports=n})();
+(()=>{"use strict";var e={698:(e,t)=>{var r=Symbol.for("react.transitional.element");function n(e,t,n){var o=null;if(void 0!==n&&(o=""+n),void 0!==t.key&&(o=""+t.key),"key"in t)for(var u in n={},t)"key"!==u&&(n[u]=t[u]);else n=t;return t=n.ref,{$$typeof:r,type:e,key:o,ref:void 0!==t?t:null,props:n}}Symbol.for("react.fragment"),t.jsx=n},848:(e,t,r)=>{e.exports=r(698)}},t={};function r(n){var o=t[n];if(void 0!==o)return o.exports;var u=t[n]={exports:{}};return e[n](u,u.exports,r),u.exports}r.d=(e,t)=>{for(var n in t)r.o(t,n)&&!r.o(e,n)&&Object.defineProperty(e,n,{enumerable:!0,get:t[n]})},r.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),r.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var n={};r.r(n),r.d(n,{Context:()=>i,default:()=>f,reallyReactiveVal:()=>c,useReactiveEffect:()=>l,useReactiveValueContext:()=>a});const o=require("react");var u=r(848);function f(e){return(0,o.useMemo)((function(){return c(e)}),[e])}var i=(0,o.createContext)(null),a=function(){return(0,o.useContext)(i)},c=function(e){var t=e,r=new Set,n=new Set,f=new Map,a=(0,o.memo)((function(){return(0,o.useSyncExternalStore)((function(e){return r.add(e),function(){return r.delete(e)}}),(function(){return t}))}));var c=Object.assign((function(e){if(void 0===e)return(0,u.jsx)(a,{});t!==(t="function"==typeof e?e(t):e)&&(n.forEach((function(e){var t=f.get(e);t&&t()})),n.forEach((function(e){var r=e(t);f.set(e,r)}))),r.forEach((function(e){e()}))}),{effect:function(e){n.add(e);var r=e(t);return f.set(e,r),function(){n.delete(e);var t=f.get(e);t&&t(),f.delete(e)}}});return[c,(0,o.memo)((function(e){var t=e.children;return(0,u.jsx)(i.Provider,{value:c,children:t})}))]},l=function(e,t){(0,o.useEffect)((function(){return e.effect(t)}),[e,t])};module.exports=n})();

package/dist/index.d.ts

@@ -1,9 +1,14 @@
-import { type ReactNode, type ReactElement, type JSX } from 'react';
-export default function useReactiveValue<T extends ReactNode>(initialValue: T): (JSX.Element | FnType<T>)[];
+import { type ReactNode, type ReactElement, PropsWithChildren, type JSX } from 'react';
+export default function useReactiveValue<T extends ReactNode>(initialValue: T): readonly [FnType<T>, (props: PropsWithChildren) => JSX.Element];
 type UpdaterType<T> = T | ((currVal: T) => T);
-type FnType<T> = <U extends UpdaterType<T> | unknown | undefined>(updater?: U) => U extends UpdaterType<T> ? undefined : ReactElement;
+type EffectCallback<T> = (value: T) => void | (() => void);
+type FnType<T> = {
+    <U extends UpdaterType<T> | unknown | undefined>(updater?: U): U extends UpdaterType<T> ? undefined : ReactElement;
+    effect: (callback: EffectCallback<T>) => () => void;
+};
 export declare const Context: import("react").Context<FnType<ReactElement<unknown, string | import("react").JSXElementConstructor<any>>> | null>;
 export declare const useReactiveValueContext: () => FnType<ReactElement<unknown, string | import("react").JSXElementConstructor<any>>> | null;
-export declare const reallyReactiveVal: <T extends ReactNode>(initialValue: T) => (FnType<T> | JSX.Element)[];
+export declare const reallyReactiveVal: <T extends ReactNode>(initialValue: T) => readonly [FnType<T>, (props: PropsWithChildren) => JSX.Element];
+export declare const useReactiveEffect: <T extends ReactNode>(reactiveValue: FnType<T>, callback: EffectCallback<T>) => void;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,YAAY,EAOjB,KAAK,GAAG,EACT,MAAM,OAAO,CAAC;AAGf,MAAM,CAAC,OAAO,UAAU,gBAAgB,CAAC,CAAC,SAAS,SAAS,EAAE,YAAY,EAAE,CAAC,+BAE5E;AAED,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9C,KAAK,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,SAAS,EAC9D,OAAO,CAAC,EAAE,CAAC,KACR,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,YAAY,CAAC;AAEzD,eAAO,MAAM,OAAO,oHAAmD,CAAC;AAExE,eAAO,MAAM,uBAAuB,iGAEnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,SAAS,EAAE,cAAc,CAAC,gCAyCrE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,YAAY,EAMjB,iBAAiB,EACjB,KAAK,GAAG,EAET,MAAM,OAAO,CAAC;AAGf,MAAM,CAAC,OAAO,UAAU,gBAAgB,CAAC,CAAC,SAAS,SAAS,EAAE,YAAY,EAAE,CAAC,gCA4FlD,iBAAiB,KAAK,GAAG,CAAC,OAAO,EA1F3D;AAED,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9C,KAAK,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;AAC3D,KAAK,MAAM,CAAC,CAAC,IAAI;IACf,CAAC,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,SAAS,EAC7C,OAAO,CAAC,EAAE,CAAC,GACV,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,YAAY,CAAC;IACvD,MAAM,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC;CACrD,CAAC;AAEF,eAAO,MAAM,OAAO,oHAAmD,CAAC;AAExE,eAAO,MAAM,uBAAuB,iGAEnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,SAAS,EAAE,cAAc,CAAC,kCAyE3C,iBAAiB,KAAK,GAAG,CAAC,OAAO,CAG3D,CAAC;AAGF,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,SAAS,EACnD,eAAe,MAAM,CAAC,CAAC,CAAC,EACxB,UAAU,cAAc,CAAC,CAAC,CAAC,SAK5B,CAAC"}

package/dist/index.esm.js

@@ -1,2 +1,2 @@
 /*! For license information please see index.esm.js.LICENSE.txt */
-import*as e from"react";var r={698:(e,r)=>{var t=Symbol.for("react.transitional.element");function n(e,r,n){var o=null;if(void 0!==n&&(o=""+n),void 0!==r.key&&(o=""+r.key),"key"in r)for(var u in n={},r)"key"!==u&&(n[u]=r[u]);else n=r;return r=n.ref,{$$typeof:t,type:e,key:o,ref:void 0!==r?r:null,props:n}}Symbol.for("react.fragment"),r.jsx=n},848:(e,r,t)=>{e.exports=t(698)}},t={};function n(e){var o=t[e];if(void 0!==o)return o.exports;var u=t[e]={exports:{}};return r[e](u,u.exports,n),u.exports}n.d=(e,r)=>{for(var t in r)n.o(r,t)&&!n.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:r[t]})},n.o=(e,r)=>Object.prototype.hasOwnProperty.call(e,r);const o=(e=>{var r={};return n.d(r,e),r})({createContext:()=>e.createContext,memo:()=>e.memo,useContext:()=>e.useContext,useMemo:()=>e.useMemo,useSyncExternalStore:()=>e.useSyncExternalStore});var u=n(848);function a(e){return(0,o.useMemo)((function(){return f(e)}),[e])}var i=(0,o.createContext)(null),c=function(){return(0,o.useContext)(i)},f=function(e){var r=e,t=new Set,n=(0,o.memo)((function(){return(0,o.useSyncExternalStore)((function(e){return t.add(e),function(){return t.delete(e)}}),(function(){return r}))}));function a(e){if(void 0===e)return(0,u.jsx)(n,{});r="function"==typeof e?e(r):e,t.forEach((function(e){e()}))}return[a,(0,o.memo)((function(e){var r=e.children;return(0,u.jsx)(i.Provider,{value:a,children:r})}))]};export{i as Context,a as default,f as reallyReactiveVal,c as useReactiveValueContext};
+import*as e from"react";var t={698:(e,t)=>{var r=Symbol.for("react.transitional.element");function n(e,t,n){var o=null;if(void 0!==n&&(o=""+n),void 0!==t.key&&(o=""+t.key),"key"in t)for(var u in n={},t)"key"!==u&&(n[u]=t[u]);else n=t;return t=n.ref,{$$typeof:r,type:e,key:o,ref:void 0!==t?t:null,props:n}}Symbol.for("react.fragment"),t.jsx=n},848:(e,t,r)=>{e.exports=r(698)}},r={};function n(e){var o=r[e];if(void 0!==o)return o.exports;var u=r[e]={exports:{}};return t[e](u,u.exports,n),u.exports}n.d=(e,t)=>{for(var r in t)n.o(t,r)&&!n.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},n.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t);const o=(e=>{var t={};return n.d(t,e),t})({createContext:()=>e.createContext,memo:()=>e.memo,useContext:()=>e.useContext,useEffect:()=>e.useEffect,useMemo:()=>e.useMemo,useSyncExternalStore:()=>e.useSyncExternalStore});var u=n(848);function f(e){return(0,o.useMemo)((function(){return i(e)}),[e])}var c=(0,o.createContext)(null),a=function(){return(0,o.useContext)(c)},i=function(e){var t=e,r=new Set,n=new Set,f=new Map,a=(0,o.memo)((function(){return(0,o.useSyncExternalStore)((function(e){return r.add(e),function(){return r.delete(e)}}),(function(){return t}))}));var i=Object.assign((function(e){if(void 0===e)return(0,u.jsx)(a,{});t!==(t="function"==typeof e?e(t):e)&&(n.forEach((function(e){var t=f.get(e);t&&t()})),n.forEach((function(e){var r=e(t);f.set(e,r)}))),r.forEach((function(e){e()}))}),{effect:function(e){n.add(e);var r=e(t);return f.set(e,r),function(){n.delete(e);var t=f.get(e);t&&t(),f.delete(e)}}});return[i,(0,o.memo)((function(e){var t=e.children;return(0,u.jsx)(c.Provider,{value:i,children:t})}))]},s=function(e,t){(0,o.useEffect)((function(){return e.effect(t)}),[e,t])};export{c as Context,f as default,i as reallyReactiveVal,s as useReactiveEffect,a as useReactiveValueContext};

package/dist/index.umd.js

@@ -1,2 +1,2 @@
 /*! For license information please see index.umd.js.LICENSE.txt */
-!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("react")):"function"==typeof define&&define.amd?define("ReactReactiveVal",["react"],t):"object"==typeof exports?exports.ReactReactiveVal=t(require("react")):e.ReactReactiveVal=t(e.React)}(this,(e=>(()=>{"use strict";var t={442:t=>{t.exports=e},698:(e,t)=>{var r=Symbol.for("react.transitional.element");function n(e,t,n){var o=null;if(void 0!==n&&(o=""+n),void 0!==t.key&&(o=""+t.key),"key"in t)for(var u in n={},t)"key"!==u&&(n[u]=t[u]);else n=t;return t=n.ref,{$$typeof:r,type:e,key:o,ref:void 0!==t?t:null,props:n}}Symbol.for("react.fragment"),t.jsx=n},848:(e,t,r)=>{e.exports=r(698)}},r={};function n(e){var o=r[e];if(void 0!==o)return o.exports;var u=r[e]={exports:{}};return t[e](u,u.exports,n),u.exports}n.n=e=>{var t=e&&e.__esModule?()=>e.default:()=>e;return n.d(t,{a:t}),t},n.d=(e,t)=>{for(var r in t)n.o(t,r)&&!n.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},n.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),n.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var o={};n.r(o),n.d(o,{Context:()=>c,default:()=>i,reallyReactiveVal:()=>l,useReactiveValueContext:()=>f});var u=n(442),a=n(848);function i(e){return(0,u.useMemo)((function(){return l(e)}),[e])}var c=(0,u.createContext)(null),f=function(){return(0,u.useContext)(c)},l=function(e){var t=e,r=new Set,n=(0,u.memo)((function(){return(0,u.useSyncExternalStore)((function(e){return r.add(e),function(){return r.delete(e)}}),(function(){return t}))}));function o(e){if(void 0===e)return(0,a.jsx)(n,{});t="function"==typeof e?e(t):e,r.forEach((function(e){e()}))}return[o,(0,u.memo)((function(e){var t=e.children;return(0,a.jsx)(c.Provider,{value:o,children:t})}))]};return o})()));
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("react")):"function"==typeof define&&define.amd?define("ReactReactiveVal",["react"],t):"object"==typeof exports?exports.ReactReactiveVal=t(require("react")):e.ReactReactiveVal=t(e.React)}(this,(e=>(()=>{"use strict";var t={442:t=>{t.exports=e},698:(e,t)=>{var r=Symbol.for("react.transitional.element");function n(e,t,n){var o=null;if(void 0!==n&&(o=""+n),void 0!==t.key&&(o=""+t.key),"key"in t)for(var u in n={},t)"key"!==u&&(n[u]=t[u]);else n=t;return t=n.ref,{$$typeof:r,type:e,key:o,ref:void 0!==t?t:null,props:n}}Symbol.for("react.fragment"),t.jsx=n},848:(e,t,r)=>{e.exports=r(698)}},r={};function n(e){var o=r[e];if(void 0!==o)return o.exports;var u=r[e]={exports:{}};return t[e](u,u.exports,n),u.exports}n.n=e=>{var t=e&&e.__esModule?()=>e.default:()=>e;return n.d(t,{a:t}),t},n.d=(e,t)=>{for(var r in t)n.o(t,r)&&!n.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},n.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),n.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var o={};n.r(o),n.d(o,{Context:()=>c,default:()=>f,reallyReactiveVal:()=>l,useReactiveEffect:()=>d,useReactiveValueContext:()=>i});var u=n(442),a=n(848);function f(e){return(0,u.useMemo)((function(){return l(e)}),[e])}var c=(0,u.createContext)(null),i=function(){return(0,u.useContext)(c)},l=function(e){var t=e,r=new Set,n=new Set,o=new Map,f=(0,u.memo)((function(){return(0,u.useSyncExternalStore)((function(e){return r.add(e),function(){return r.delete(e)}}),(function(){return t}))}));var i=Object.assign((function(e){if(void 0===e)return(0,a.jsx)(f,{});t!==(t="function"==typeof e?e(t):e)&&(n.forEach((function(e){var t=o.get(e);t&&t()})),n.forEach((function(e){var r=e(t);o.set(e,r)}))),r.forEach((function(e){e()}))}),{effect:function(e){n.add(e);var r=e(t);return o.set(e,r),function(){n.delete(e);var t=o.get(e);t&&t(),o.delete(e)}}});return[i,(0,u.memo)((function(e){var t=e.children;return(0,a.jsx)(c.Provider,{value:i,children:t})}))]},d=function(e,t){(0,u.useEffect)((function(){return e.effect(t)}),[e,t])};return o})()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-reactive-val",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "A lightweight, type-safe reactive value management library for React applications",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",