shablon 0.0.1-rc.3 → 0.0.1-rc.5

package/README.md

@@ -6,7 +6,7 @@ Shablon - No-build JavaScript frontend framework
 >
 > **Don't use it yet - it hasn't been actually tested in real applications and it may change without notice!**
 
-**Shablon** _("template" in Bulgarian)_ is a ~5KB JS framework that comes with deeply reactive state management, plain JS extendable templates and hash-based router.
+**Shablon** _("template" in Bulgarian)_ is a ~6KB JS framework that comes with deeply reactive state management, plain JS extendable templates and hash-based router.
 
 Shablon has very small learning curve (**4 main exported functions**) and it is suitable for building Single-page applications (SPA):
 
@@ -142,7 +142,7 @@ importing it from [npm](https://www.npmjs.com/package/shablon).
 
 The keys of an `obj` must be "stringifiable" because they are used internally to construct a path to the reactive value.
 
-The values can be any valid JS value, including nested arrays and objects (aka. it is recursively reactive).
+The values can be any valid JS primitive value, including nested plain arrays and objects (aka. it is recursively reactive).
 
 Getters are also supported and can be used as reactive computed properties.
 The value of a reactive getter is "cached", meaning that even if one of the getter dependency changes, as long as the resulting value is the same there will be no unnecessary watch events fired.
@@ -162,6 +162,9 @@ data.age++
 data.activity = "rest"
 ```
 
+> Note that only plain objects and arrays are wrapped in a nested `Proxy`! `Date`, `Set`, `Map`, `WeakRef`, `WeakSet`, `WeakMap` or any custom object will be resolved as they are to avoid access errors.
+> You can access the original object without the Proxy trap using the special `__raw` key, e.g. `data.someObj.__raw.someKey`.
+
 </details>
 
 
@@ -171,6 +174,8 @@ data.activity = "rest"
 Watch registers a callback function that fires on initialization and
 every time any of its evaluated `store` reactive properties change.
 
+Note that for reactive getters, initially the watch `trackedFunc` will be invoked twice because we register a second internal watcher to cache the getter value.
+
 It returns a "watcher" object that could be used to `unwatch()` the registered listener.
 
 _Optionally also accepts a second callback function that is excluded from the evaluated
@@ -204,7 +209,7 @@ const data = store({
 watch(() => [
    data.a,
    data.b,
-], () => {
+], (_) => { // receive the return result of trackedFunc
     console.log(data.a)
     console.log(data.b)
     console.log(data.c)
@@ -215,8 +220,6 @@ data.b++ // trigger watch update
 data.c++ // doesn't trigger watch update
 ```
 
-Note that for reactive getters, initially the watch trackCallback will be invoked twice because we register a second internal watcher to cache the getter value.
-
 </details>
 
 

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "0.0.1-rc.3",
+    "version": "0.0.1-rc.5",
     "name": "shablon",
     "description": "No-build JavaScript framework for Single-page applications",
     "author": "Gani Georgiev",

package/src/router.js

@@ -49,7 +49,7 @@ export function router(routes, options = { fallbackPath: "#/", transition: true
         if (!route) {
             if (options.fallbackPath != path) {
                 window.location.hash = options.fallbackPath;
-                return
+                return;
             }
 
             console.warn("missing route:", path);
@@ -120,7 +120,8 @@ function prepareRoutes(routes) {
                 parts[i].endsWith("}")
             ) {
                 // param
-                parts[i] = "(?<" + parts[i].substring(1, parts[i].length - 1) + ">[^\\/#?]+)";
+                parts[i] =
+                    "(?<" + parts[i].substring(1, parts[i].length - 1) + ">[^\\/#?]+)";
             } else {
                 // regular path segment
                 parts[i] = RegExp.escape(parts[i]);

package/src/state.js

@@ -7,11 +7,14 @@ let cleanTimeoutId;
 
 let idSym = Symbol();
 let parentSym = Symbol();
-let pathsResetedSym = Symbol();
 let childrenSym = Symbol();
 let pathsSubsSym = Symbol();
 let unwatchedSym = Symbol();
 let onRemoveSym = Symbol();
+let skipSym = Symbol();
+let evictedSym = Symbol();
+
+let pathSeparator = "/";
 
 /**
  * Watch registers a callback function that fires on initialization and
@@ -68,7 +71,7 @@ let onRemoveSym = Symbol();
 export function watch(trackedFunc, optUntrackedFunc) {
     let watcher = {
         [idSym]: "_" + Math.random(),
-    }
+    };
 
     allWatchers.set(watcher[idSym], watcher);
 
@@ -77,7 +80,7 @@ export function watch(trackedFunc, optUntrackedFunc) {
 
         // nested watcher -> register previous watcher as parent
         if (activeWatcher) {
-            oldActiveWatcher = activeWatcher
+            oldActiveWatcher = activeWatcher;
             watcher[parentSym] = activeWatcher[idSym];
 
             // store immediate children references for quicker cleanup
@@ -85,12 +88,44 @@ export function watch(trackedFunc, optUntrackedFunc) {
             activeWatcher[childrenSym].push(watcher[idSym]);
         }
 
+        // On watcher function run, resets any previous tracking paths
+        // because after this new run some of the old dependencies
+        // may no longer be reachable/evaluatable.
+        //
+        // For example, in the below code:
+        //
+        // ```js
+        // const data = store({ a: 0, b: 0, c: 0 })
+        //
+        // watch(() => {
+        //     if (data.a > 0) {
+        //         data.b
+        //     } else {
+        //         data.c
+        //     }
+        // })
+        // ```
+        //
+        // initially ONLY "a" and "c" should be trackable because "b"
+        // is not reachable (aka. its getter is never invoked).
+        //
+        // If we increment `a++`, then in the new run  ONLY "a" and "b" should be trackable
+        // because this time "c" is not reachable (aka. its getter is never invoked)
+        // and its previous tracking should be removed for this watcher.
+        //
+        // Note: The below code works because it reuses the same "subs" reference as in pathWatcherIds
+        //       and this is intentional to avoid unnecessary iterations.
+        watcher[pathsSubsSym]?.forEach((subs) => {
+            subs.delete(watcher[idSym]);
+        });
+
         activeWatcher = watcher;
-        activeWatcher[pathsResetedSym] = false;
-        watcher.last = trackedFunc();
+        const result = trackedFunc();
 
-        activeWatcher = null;
-        optUntrackedFunc?.();
+        if (optUntrackedFunc) {
+            activeWatcher = null;
+            optUntrackedFunc(result);
+        }
 
         // restore original ref (if any)
         activeWatcher = oldActiveWatcher;
@@ -135,10 +170,8 @@ function removeWatcher(id) {
     }
 
     if (w?.[pathsSubsSym]) {
-        for (let subset of w[pathsSubsSym]) {
-            if (subset.has(id)) {
-                subset.delete(id);
-            }
+        for (let sub of w[pathsSubsSym]) {
+            sub.delete(id);
         }
         w[pathsSubsSym] = null;
     }
@@ -185,12 +218,65 @@ function createProxy(obj, pathWatcherIds) {
             ? Object.getOwnPropertyDescriptors(obj)
             : {};
 
-    let handler = {
-        get(obj, prop, target) {
-            if (prop === "__raw") {
+    return new Proxy(obj, {
+        get(obj, prop, receiver) {
+            if (typeof prop == "symbol") {
+                return obj[prop];
+            }
+
+            if (prop == "__raw") {
                 return obj;
             }
 
+            // evicted child?
+            if (!obj[skipSym] && obj[parentSym]) {
+                let props = [];
+                let activeObj = obj;
+
+                let isEvicted = false;
+
+                // travel up to the root proxy
+                // (aka. x.a.b*.c -> x)
+                while (activeObj?.[parentSym]) {
+                    if (activeObj[evictedSym]) {
+                        isEvicted = true;
+                    }
+
+                    props.push(activeObj[parentSym][1]);
+                    activeObj = activeObj[parentSym][0];
+                }
+
+                // try to access the original path but this time from
+                // the root point of view to ensure that we are always accessing
+                // an up-to-date store child reference
+                // (we want: x.a.b(old).c -> x -> x.a.b(new).c)
+                //
+                // note: this technically could "leak" but for our case it should be fine
+                // because the evicted object will become again garbage collectable
+                // once the related watcher(s) are removed
+                if (isEvicted) {
+                    for (let i = props.length - 1; i >= 0; i--) {
+                        activeObj[skipSym] = true;
+                        let item = activeObj?.[props[i]];
+                        activeObj[skipSym] = false;
+
+                        if (i == 0) {
+                            activeObj = item?.__raw;
+                        } else {
+                            activeObj = item;
+                        }
+                    }
+
+                    // the original full nested path is no longer available (null/undefined)
+                    if (activeObj == undefined) {
+                        return activeObj;
+                    }
+
+                    // update the current obj with the one from the retraced path
+                    obj = activeObj;
+                }
+            }
+
             // getter?
             let getterProp;
             if (descriptors[prop]?.get) {
@@ -202,24 +288,30 @@ function createProxy(obj, pathWatcherIds) {
 
                 getterProp = prop;
 
-                // replace with an internal "@prop" property so that
+                // replace with an internal "@@prop" property so that
                 // reactive statements can be cached
-                prop = "@" + prop;
+                prop = "@@" + prop;
             }
 
-            // directly return symbols and functions (pop, push, etc.)
-            if (typeof prop == "symbol" || typeof obj[prop] == "function") {
-                return obj[prop];
+            let propVal = obj[prop];
+
+            // directly return for functions (pop, push, etc.)
+            if (typeof propVal == "function") {
+                return propVal;
             }
 
-            // wrap child object or array as sub store
+            // wrap child plain object or array as sub store
             if (
-                typeof obj[prop] == "object" &&
-                obj[prop] !== null &&
-                !obj[prop][parentSym]
+                propVal != null &&
+                typeof propVal == "object" &&
+                !propVal[parentSym] &&
+                (propVal.constructor?.name == "Object" ||
+                    propVal.constructor?.name == "Array" ||
+                    propVal.constructor?.name == undefined) // e.g. Object.create(null)
             ) {
-                obj[prop][parentSym] = [obj, prop];
-                obj[prop] = createProxy(obj[prop], pathWatcherIds);
+                propVal[parentSym] = [receiver, prop];
+                propVal = createProxy(propVal, pathWatcherIds);
+                obj[prop] = propVal;
             }
 
             // register watch subscriber (if any)
@@ -227,52 +319,36 @@ function createProxy(obj, pathWatcherIds) {
                 let currentPath = getPath(obj, prop);
                 let activeWatcherId = activeWatcher[idSym];
 
+                let propPaths = [currentPath];
+
+                // always construct all parent paths ("x.a.b.c" => ["a", "a.b", "a.b.c"])
+                // because a store child object can be passed as argument to a function
+                // and in that case the parents proxy get trap will not be invoked,
+                // and their path will not be registered
+                if (obj[parentSym]) {
+                    let parts = currentPath.split(pathSeparator);
+                    while (parts.pop() && parts.length) {
+                        propPaths.push(parts.join(pathSeparator));
+                    }
+                }
+
+                // initialize a watcher paths tracking set (if not already)
                 activeWatcher[pathsSubsSym] = activeWatcher[pathsSubsSym] || new Set();
 
-                // If this is a rerun of the watcher function, resets any previous
-                // tracking paths because after this new run some of the old
-                // dependencies may no longer be reachable/evaluatable.
-                //
-                // For example, in the below code:
-                //
-                // ```js
-                // const data = store({ a: 0, b: 0, c: 0 })
-                //
-                // watch(() => {
-                //     if (data.a > 0) {
-                //         data.b
-                //     } else {
-                //         data.c
-                //     }
-                // })
-                // ```
-                //
-                // initially ONLY "a" and "c" should be trackable because "b"
-                // is not reachable (aka. its getter is never invoked).
-                //
-                // If we increment `a++`, then in the new run  ONLY "a" and "b" should be trackable
-                // because this time "c" is not reachable (aka. its getter is never invoked)
-                // and its previous tracking should be removed for this watcher.
-                //
-                // Note: The below code works because it reuses the same "subs" reference as in pathWatcherIds
-                //       and this is intentional to avoid unnecessary iterations.
-                if (!activeWatcher[pathsResetedSym]) {
-                    activeWatcher[pathsSubsSym].forEach((subs) => {
-                        subs.delete(activeWatcherId)
-                    })
-                    activeWatcher[pathsResetedSym] = true;
-                }
+                // register the paths to watch
+                for (let path of propPaths) {
+                    let subs = pathWatcherIds.get(path);
+                    if (!subs) {
+                        subs = new Set();
+                        pathWatcherIds.set(path, subs);
+                    }
 
-                let subs = pathWatcherIds.get(currentPath);
-                if (!subs) {
-                    subs = new Set();
-                    pathWatcherIds.set(currentPath, subs);
-                }
-                subs.add(activeWatcherId);
+                    subs.add(activeWatcherId);
 
-                activeWatcher[pathsSubsSym].add(subs);
+                    activeWatcher[pathsSubsSym].add(subs);
+                }
 
-                // register a child watcher to update the custom getter prop replacement
+                // register an extra child watcher to update the custom getter prop replacement
                 // (should be removed automatically with the removal of the parent watcher)
                 if (
                     getterProp &&
@@ -284,7 +360,7 @@ function createProxy(obj, pathWatcherIds) {
 
                     let getFunc = descriptors[getterProp].get.bind(obj);
 
-                    let getWatcher = watch(() => (target[prop] = getFunc()));
+                    let getWatcher = watch(() => (receiver[prop] = getFunc()));
 
                     getWatcher[onRemoveSym] = () => {
                         descriptors[getterProp]?.watchers?.delete(watcherId);
@@ -292,7 +368,7 @@ function createProxy(obj, pathWatcherIds) {
                 }
             }
 
-            return obj[prop];
+            return propVal;
         },
         set(obj, prop, value) {
             if (typeof prop == "symbol") {
@@ -301,6 +377,17 @@ function createProxy(obj, pathWatcherIds) {
             }
 
             let oldValue = obj[prop];
+
+            // mark as "evicted" in case a proxy child object/array is being replaced
+            if (oldValue?.[parentSym]) {
+                oldValue[evictedSym] = true;
+            }
+
+            // update the stored parent reference in case of index change (e.g. unshift)
+            if (value?.[parentSym] && Array.isArray(obj) && !isNaN(prop)) {
+                value[parentSym][1] = prop;
+            }
+
             obj[prop] = value;
 
             // trigger only on value change
@@ -316,18 +403,22 @@ function createProxy(obj, pathWatcherIds) {
                 callWatchers(obj, prop, pathWatcherIds);
 
                 let currentPath = getPath(obj, prop);
-                if (pathWatcherIds.has(currentPath)) {
-                    pathWatcherIds.delete(currentPath);
+
+                for (const item of pathWatcherIds) {
+                    if (
+                        // exact match
+                        item[0] == currentPath ||
+                        // child path
+                        item[0].startsWith(currentPath + pathSeparator)
+                    ) {
+                        pathWatcherIds.delete(item[0]);
+                    }
                 }
             }
 
-            delete obj[prop];
-
-            return true;
+            return delete obj[prop];
         },
-    };
-
-    return new Proxy(obj, handler);
+    });
 }
 
 function getPath(obj, prop) {
@@ -335,7 +426,7 @@ function getPath(obj, prop) {
 
     let parentData = obj?.[parentSym];
     while (parentData) {
-        currentPath = parentData[1] + "." + currentPath;
+        currentPath = parentData[1] + pathSeparator + currentPath;
         parentData = parentData[0][parentSym];
     }
 

package/src/template.js

@@ -97,7 +97,9 @@ function tag(tagName, attrs = {}, ...children) {
                 attr = attr.substring(5);
             }
 
-            if (
+            if (typeof val === "undefined") {
+                el.removeAttribute(attr);
+            } else if (
                 // JS property or regular HTML attribute
                 typeof val != "function" ||
                 // event
@@ -192,6 +194,8 @@ function setChildren(el, children) {
     }
 }
 
+// Note: Direct nested reactive functions or direct nested arrays are not supported,
+// aka. childrenFunc must return a single element or plain array of elements.
 function initChildrenFuncWatcher(el, childrenFunc) {
     let endPlaceholder = document.createComment("");
     el.appendChild(endPlaceholder);
@@ -398,7 +402,11 @@ function toArray(val) {
 
 function normalizeNode(child) {
     // wrap as TextNode so that it can be "tracked" and used with appendChild or other similar methods
-    if (typeof child == "string" || typeof child == "number" || typeof child == "boolean") {
+    if (
+        typeof child == "string" ||
+        typeof child == "number" ||
+        typeof child == "boolean"
+    ) {
         let childNode = document.createTextNode(child);
         childNode.rid = child;
         return childNode;
@@ -406,7 +414,7 @@ function normalizeNode(child) {
 
     // in case child is DOM Proxy element/array loaded from a store object
     if (typeof child?.__raw != "undefined") {
-        return child.__raw
+        return child.__raw;
     }
 
     return child;