shablon 0.0.1-rc.4 → 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):
 
@@ -162,8 +162,8 @@ data.age++
 data.activity = "rest"
 ```
 
-> Note that Object values like `Date`, `Set`, `Map`, `WeakRef`, `WeakSet` and `WeakMap` values are not wrapped in a nested `Proxy` and they will be resolved as they are to avoid access errors.
-> For other custom object types thay you may want to access without a `Proxy` you can use the special `__raw` key, e.g. `data.myCustomType.__raw.someKey`.
+> 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>
 
@@ -209,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)

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "0.0.1-rc.4",
+    "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,26 +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;
             }
 
-            const propVal = obj[prop]
+            let propVal = obj[prop];
 
-            // directly return symbols and functions (pop, push, etc.)
-            if (typeof prop == "symbol" || typeof propVal == "function") {
+            // 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 (
-                propVal !== null && typeof propVal == "object" &&
+                propVal != null &&
+                typeof propVal == "object" &&
                 !propVal[parentSym] &&
-                !isExcludedInstance(propVal)
+                (propVal.constructor?.name == "Object" ||
+                    propVal.constructor?.name == "Array" ||
+                    propVal.constructor?.name == undefined) // e.g. Object.create(null)
             ) {
-                propVal[parentSym] = [obj, prop];
-                obj[prop] = createProxy(propVal, pathWatcherIds);
+                propVal[parentSym] = [receiver, prop];
+                propVal = createProxy(propVal, pathWatcherIds);
+                obj[prop] = propVal;
             }
 
             // register watch subscriber (if any)
@@ -229,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 &&
@@ -286,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);
@@ -294,7 +368,7 @@ function createProxy(obj, pathWatcherIds) {
                 }
             }
 
-            return obj[prop];
+            return propVal;
         },
         set(obj, prop, value) {
             if (typeof prop == "symbol") {
@@ -303,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
@@ -318,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) {
@@ -337,24 +426,13 @@ function getPath(obj, prop) {
 
     let parentData = obj?.[parentSym];
     while (parentData) {
-        currentPath = parentData[1] + "." + currentPath;
+        currentPath = parentData[1] + pathSeparator + currentPath;
         parentData = parentData[0][parentSym];
     }
 
     return currentPath;
 }
 
-function isExcludedInstance(val) {
-    return (
-        (val instanceof Date) ||
-        (val instanceof Set) ||
-        (val instanceof Map) ||
-        (val instanceof WeakRef) ||
-        (val instanceof WeakMap) ||
-        (val instanceof WeakSet)
-    )
-}
-
 function callWatchers(obj, prop, pathWatcherIds) {
     let currentPath = getPath(obj, prop);
 

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;