react-deepwatch 1.0.0 → 1.1.1

package/index.ts

@@ -4,15 +4,19 @@ import {
     RecordedValueRead,
     WatchedProxyFacade, installChangeTracker
 } from "proxy-facades";
-import {arraysAreEqualsByPredicateFn, isObject, PromiseState, recordedReadsArraysAreEqual, throwError} from "./Util";
+import {
+    arraysAreEqualsByPredicateFn,
+    isObject,
+    newDefaultMap,
+    PromiseState,
+    recordedReadsArraysAreEqual,
+    throwError
+} from "./Util";
 import {useLayoutEffect, useState, createElement, Fragment, ReactNode, useEffect, useContext, memo} from "react";
 import {ErrorBoundaryContext, useErrorBoundary} from "react-error-boundary";
 import {_preserve, preserve, PreserveOptions} from "./preserve";
 
-let watchedProxyFacade: WatchedProxyFacade | undefined
-function getWatchedProxyFacade() {
-    return watchedProxyFacade || (watchedProxyFacade = new WatchedProxyFacade()); // Lazy initialize global variable
-}
+let sharedWatchedProxyFacade: WatchedProxyFacade | undefined
 
 let debug_idGenerator=0;
 
@@ -34,12 +38,10 @@ type WatchedComponentOptions = {
     memo?: boolean
 
     /**
-     * TODO
      * Normally, everything that's **taken** from props, {@link useWatchedState} or {@link watched} or load(...)'s result will be returned, wrapped in a proxy that watches for modifications.
-     * So far, so good, this can handle all stuff that's happening inside your component, but the outside world does not have these proxies. For example, when a parent component is not a watchedComponent, and passed in an object (i.e. the model) into this component via props.
+     * So far, so good, this can handle all stuff that's happening **inside** your component, but the outside world does not have these proxies. For example, when a parent component is not a watchedComponent, and passed in an object (i.e. the model) into this component via props.
      * Therefore this component can also **patch** these objects to make them watchable.
      *
-     *
      * <p>Default: true</p>
      */
     watchOutside?: boolean
@@ -57,6 +59,17 @@ type WatchedComponentOptions = {
      * </p>
      */
     preserveProps?: boolean
+
+    /**
+     * Shares a global proxy facade instance for all watchedComponents. This is the more tested and easier to think about option.
+     * Disabling this creates a layer of new proxies for every of your child components. Object instances **inside** your component may still be consistent, but there could be: objInsideMyComponent !== myObjectHandedOverGloballyInSomeOtherWay. Real world use cases have to prove, if this is good way.
+     * Note:
+     * <p>
+     *  Default: true
+     * </p>
+     */
+    // Development: Note: Also keep in mind: `this.proxyHandler === other.proxyHandler` in RecordedPropertyRead#equals -> is this a problem? I assume that the component instances/state and therefore the watchedProxyFacades stay the same.
+    useGlobalSharedProxyFacade?: boolean
 }
 
 /**
@@ -306,10 +319,20 @@ class LoadCall {
 class WatchedComponentPersistent {
     options: WatchedComponentOptions;
 
+    _nonSharedWatchedProxyFacade?: WatchedProxyFacade;
+
+    get watchedProxyFacade() {
+        if(this.options.useGlobalSharedProxyFacade === false) {
+            return this._nonSharedWatchedProxyFacade || (this._nonSharedWatchedProxyFacade = new WatchedProxyFacade());
+        }
+        // Use a global shared instance
+        return sharedWatchedProxyFacade || (sharedWatchedProxyFacade = new WatchedProxyFacade()); // Lazy initialize global variable
+    }
+
     /**
      * props of the component. These are saved here in the state (in a non changing object instance), so code inside load call can watch **shallow** props changes on it.
      */
-    watchedProps = getWatchedProxyFacade().getProxyFor({});
+    watchedProps: {};
 
     /**
      * id -> loadCall. Null when there are multiple for that id
@@ -341,6 +364,12 @@ class WatchedComponentPersistent {
 
     onceOnEffectCleanupListeners: (()=>void)[] = [];
 
+    /**
+     * For the <a href="https://github.com/bogeeee/react-deepwatch/blob/main/readme.md#and-less-handing-onchange-listeners-to-child-components">"And less... handing onChange listeners to child components"</a> use case.
+     * We don't want new object instances created, every time watched(..., {onChange:....}) is called. So we assign the proxy facade (see watched function) to the object
+     */
+    object_to_childProxyFacade = newDefaultMap<object, WatchedProxyFacade>(() => new WatchedProxyFacade());
+
     debug_tag?: string;
 
     protected doReRender() {
@@ -396,6 +425,7 @@ class WatchedComponentPersistent {
 
     constructor(options: WatchedComponentOptions) {
         this.options = options;
+        this.watchedProps = this.watchedProxyFacade.getProxyFor({})
     }
 
     /**
@@ -449,12 +479,6 @@ class Frame {
 
     isListeningForChanges = false;
 
-    //watchedProxyFacade= new WatchedProxyFacade();
-    get watchedProxyFacade() {
-        // Use a global shared instance. Because there's no exclusive state inside the graph/handlers. And state.someObj = state.someObj does not cause us multiple nesting layers of proxies. Still this may not the final choice. When changing this mind also the `this.proxyHandler === other.proxyHandler` in RecordedPropertyRead#equals
-        return getWatchedProxyFacade();
-    }
-
     constructor() {
         this.watchPropertyChange_changeListenerFn = this.watchPropertyChange_changeListenerFn.bind(this); // method is handed over as function but uses "this" inside.
     }
@@ -508,7 +532,12 @@ class Frame {
                 }
             }
             catch (e) {
-                throw new Error(`Could not enhance the original object to track reads. This can fail, if it was created with some unsupported language constructs (defining read only properties; subclassing Array, Set or Map; ...). You can switch it off via the WatchedComponentOptions#watchOutside flag. I.e: const MyComponent = watchedComponent(props => {...}, {watchOutside: false})`, {cause: e});
+                if((e as Error).message?.startsWith("Cannot install change tracker on a proxy")) { // Hacky way to catch this. TODO: Expose a proper API for it.
+
+                }
+                else {
+                    throw new Error(`Could not enhance the original object to track reads. This can fail, if it was created with some unsupported language constructs (defining read only properties; subclassing Array, Set or Map; ...). You can switch it off via the WatchedComponentOptions#watchOutside flag. I.e: const MyComponent = watchedComponent(props => {...}, {watchOutside: false})`, {cause: e});
+                }
             }
         }
 
@@ -551,6 +580,18 @@ class RenderRun {
     somePending?: Promise<unknown>;
     somePendingAreCritical = false;
 
+    /**
+     * (Additional) effect functions (run after mount. Like with useEffect)
+     */
+    effectFns: (() => void)[] = [];
+
+    /**
+     * (Additional) effect cleanup functions
+     */
+    effectCleanupFns: (() => void)[] = [];
+
+    diagnosis_objectsWatchedWithOnChange = new Set<object>();
+
     handleRenderFinishedSuccessfully() {
         if(!this.isPassive) {
             // Delete unused loadCalls
@@ -572,6 +613,7 @@ class RenderRun {
     handleEffectSetup() {
         this.frame.persistent.hadASuccessfullMount = true;
         this.frame.startListeningForChanges();
+        this.effectFns.forEach(fn => fn());
     }
 
     /**
@@ -579,6 +621,7 @@ class RenderRun {
      */
     handleEffectCleanup() {
         // Call listeners:
+        this.effectCleanupFns.forEach(fn => fn());
         this.frame.persistent.onceOnEffectCleanupListeners.forEach(fn => fn());
         this.frame.persistent.onceOnEffectCleanupListeners = [];
 
@@ -654,7 +697,7 @@ export function watchedComponent<PROPS extends object>(componentFn:(props: PROPS
 
                 renderRun.recordedReads.push(read);
             };
-            frame.watchedProxyFacade.onAfterRead(readListener)
+            persistent.watchedProxyFacade.onAfterRead(readListener)
 
             try {
                 try {
@@ -694,7 +737,7 @@ export function watchedComponent<PROPS extends object>(componentFn:(props: PROPS
                 throw e;
             }
             finally {
-                frame.watchedProxyFacade.offAfterRead(readListener);
+                persistent.watchedProxyFacade.offAfterRead(readListener);
             }
         }
         finally {
@@ -712,29 +755,61 @@ export function watchedComponent<PROPS extends object>(componentFn:(props: PROPS
 
 type WatchedOptions = {
     /**
-     * TODO: Implement
      * Called, when a deep property was changed through the proxy.
+     * Setting this, will create a new proxy-facade for the purpuse of watching changes only (deep) under that proxy.
+     * <p>
+     *     <a href="https://github.com/bogeeee/react-deepwatch/blob/main/readme.md#and-less-handing-onchange-listeners-to-child-components">Usage</a>
+     * </p>
      */
     onChange?: () => void
 
     /**
-     * TODO: Implement
+     *
      * Called on a change to one of those properties, that were read-recorded in the component function (through the proxy of course).
      * Reacts also on external changes / not done through the proxy.
      */
-    onRecordedChange?: () => void
+    //onRecordedChange?: () => void
 }
 
-function watched<T extends object>(obj: T, options?: WatchedOptions): T {
+/**
+ * Watches any (external) object and tracks reads to it's deep childs. Changes to these tracked reads will result in a re-render or re-load the load(...) statements that depend on it.
+ * <p>
+ * Also you can use it with the onChange option, see the <a href="https://github.com/bogeeee/react-deepwatch/blob/main/readme.md#and-less-handing-onchange-listeners-to-child-components">"And less... handing onChange listeners to child components"</a> use case.
+ * </p>
+ * @param obj original object to watch
+ * @param options
+ * @returns a proxy for the original object.
+ */
+export function watched<T extends object>(obj: T, options?: WatchedOptions): T {
     currentRenderRun || throwError("watched is not used from inside a watchedComponent");
-    return currentRenderRun!.frame.watchedProxyFacade.getProxyFor(obj);
+    let result = currentRenderRun!.frame.persistent.watchedProxyFacade.getProxyFor(obj);
+    if(options?.onChange) {
+        // Safety check:
+        !currentRenderRun!.diagnosis_objectsWatchedWithOnChange.has(result) || throwError("You have called watched(someObject, {onChange:...}) 2 times for the same someObj. This is not supported, since for keeping as much object instance consitency as possible, there is one fixed proxyfacade-for-change-tracking assiciated to it. If you really have a valid use case for watching the same object twice for changes, submit an issue.");
+        currentRenderRun!.diagnosis_objectsWatchedWithOnChange.add(result)
+
+        const facadeForChangeWatching = currentRenderRun!.frame.persistent.object_to_childProxyFacade.get(obj);
+
+        // Listen for changes and call options.onChange during component mount:
+        const changeHandler = (changeOperation: any) => options.onChange!()
+        currentRenderRun!.effectFns.push(() => {facadeForChangeWatching.onAfterChange(changeHandler)});
+        currentRenderRun!.effectCleanupFns.push(() => {facadeForChangeWatching.offAfterChange(changeHandler)});
+
+        result = facadeForChangeWatching.getProxyFor(result);
+    }
+    return result;
 }
 
+/**
+ * Saves the state like with useState(...) and watches and tracks reads to it's deep childs. Changes to these tracked reads will result in a re-render or re-load the load(...) statements that depend on it.
+ * @param initial
+ * @param options
+ */
 export function useWatchedState(initial: object, options?: WatchedOptions) {
     currentRenderRun || throwError("useWatchedState is not used from inside a watchedComponent");
 
     const [state]  = useState(initial);
-    return watched(state);
+    return watched(state, options);
 }
 
 /**
@@ -1080,7 +1155,7 @@ export function load(loaderFn: (oldResult?: unknown) => Promise<unknown>, option
         }
     }
 
-    function watched(value: unknown) { return (value !== null && typeof value === "object")?frame.watchedProxyFacade.getProxyFor(value):value }
+    function watched(value: unknown) { return (value !== null && typeof value === "object")?persistent.watchedProxyFacade.getProxyFor(value):value }
 
     /**
      *
@@ -1234,4 +1309,6 @@ function probe<T>(probeFn: () => T, defaultResult: T) {
 
 export function debug_tagComponent(name: string) {
     currentRenderRun!.frame.persistent.debug_tag = name;
-}
+}
+
+export {preserve, PreserveOptions} from "./preserve"

package/index_esm.mjs

@@ -1,6 +1,16 @@
 // A wrapper file for ESM to avoid the 'dual package hazard'. See https://nodejs.org/api/packages.html#approach-1-use-an-es-module-wrapper
 
 
-
 import cjsIndex from "./index.js"
-export const todo = cjsIndex.todo
+export const watchedComponent = cjsIndex.watchedComponent
+export const watched = cjsIndex.watched
+export const useWatchedState = cjsIndex.useWatchedState
+export const load = cjsIndex.load
+export const isLoading = cjsIndex.isLoading
+export const loadFailed = cjsIndex.loadFailed
+export const poll = cjsIndex.poll
+export const debug_tagComponent = cjsIndex.debug_tagComponent
+
+import cjsPreserve from "./preserve.js"
+export const preserve = cjsPreserve.preserve
+export const PreserveOptions = cjsPreserve.PreserveOptions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-deepwatch",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "",
   "keywords": [
     "react",
@@ -44,9 +44,7 @@
     "react": "^18.3.1",
     "@types/react": "^18.3.11",
     "react-error-boundary": "^4.x",
-    "clone": "^2.1.2",
-    "@types/clone": "^2.1.4",
-    "proxy-facades": "^1.0.0"
+    "proxy-facades": "^1.0.5"
   },
   "devDependencies": {
     "tsx": "^4.7.0",
@@ -54,6 +52,8 @@
     "rimraf": "=5.0.5",
     "ncp": "=2.0.0",
     "typescript": "^5.4.5",
-    "vitest": "^1.5.0"
+    "vitest": "^1.5.0",
+    "clone": "^2.1.2",
+    "@types/clone": "^2.1.4"
   }
 }

package/readme.md

@@ -21,13 +21,14 @@ const MyComponent = watchedComponent(props => {
     const state = useWatchedState( {myDeep: {counter: 0, b: 2}}, {/* WatchedOptions (optional) */} );
 
     return <div>
-        Counter is: {state.myDeep.counter}
+        Counter is: {state.myDeep.counter}<br/>
       <button onClick={ () => state.myDeep.counter++ /* will trigger a rerender */ }>Increase counter</button>
     </div>
 }, {/* WatchedComponentOptions (optional) */});
 
 <MyComponent/> // Use MyComponent
 ````
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz_small.svg)](https://stackblitz.com/fork/github/bogeeee/react-deepwatch/tree/1.x/examples/no-more-setstate?title=react-deepwatch%20example&file=index.tsx)
 
 ## and less... loading code
 Now that we already have the ability to deeply record our reads, let's see if there's also a way to **cut away the boilerplate code for `useEffect`**.
@@ -83,6 +84,33 @@ To reduce the number of expensive `myFetchFromServer` calls, try the following:
 # Playground [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz_small.svg)](https://stackblitz.com/fork/github/bogeeee/react-deepwatch/tree/1.x/example?title=react-deepwatch%20example&file=index.ts)
 TODO
 
+# And less... handing onChange listeners to child components
+Since we have proxy-facades, we can easily hook on, whenever some deep data changes and don't need to manage that with callback- passing to child-child components.
+Let's say, we have a form and a child component, that modifies it. We are interested in changes, so we can send the form content to the server.
+````jsx
+import {watchedComponent, watched, useWatchedState} from "react-deepwatch"
+const MyParentComponent = watchedComponent(props => {
+    const myState = useWatchedState({
+        form: {
+            name: "",
+            address: ""
+        }
+    }, {onChange: () => console.log("Something deep inside myState has changed")}); // Option 1: You can hook here
+
+    return <form>        
+        <ChildComponentThatModifiesForm form={ // let's pass a special version of myState.form to the child component which calls our onChange handler
+            watched(myState.form, {
+                onChange: () => {postFormToTheSerer(myState.form); console.log("Somthing under myState.form was changed")} // Option 2: You can also hook here
+            })
+        }/>
+    </form>
+});
+````
+_This example will trigger both onChange handlers._
+
+_Note, that `watched(myState.form) !== myState.form`. It created a new proxy object in a new proxy-facade layer here, just for the purpose of deep-watching everything under it. Sometimes you may want to take advantage of it, so that modifications in the originaly layer (in MyParentComponent) won't fire the onChange event / call the postFormToTheSerer function. I.e. for updates that came from the server_
+
+
 # Further notes
 
 ### watched