shablon 0.0.1-rc.2 → 0.0.1-rc.4

package/README.md

@@ -10,7 +10,7 @@ Shablon - No-build JavaScript frontend framework
 
 Shablon has very small learning curve (**4 main exported functions**) and it is suitable for building Single-page applications (SPA):
 
-- State: `store(obj)` and `watch(callback)`
+- State: `store(obj)` and `watch(trackedFunc, optUntrackedFunc)`
 - Template: `t.[tag](attrs, ...children)`
 - Router: `router(routes, options)`
 
@@ -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,16 +162,25 @@ 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`.
+
 </details>
 
 
 <details>
-<summary><strong id="api.watch">watch(callback)</strong></summary>
+<summary><strong id="api.watch">watch(trackedFunc, optUntrackedFunc)</strong></summary>
+
+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.
 
-Watch registers a callback function that fires once on initialization and
-every time any of its `store` reactive dependencies change.
+It returns a "watcher" object that could be used to `unwatch()` the registered listener.
 
-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
+store props tracking and instead is invoked only when `trackedFunc` is called
+(could be used as a "track-only" watch pattern)._
 
 For example:
 
@@ -187,7 +196,29 @@ w.unwatch()
 data.count++ // doesn't trigger watch update
 ```
 
-Note that for reactive getters, initially the watch callback will be invoked twice because we register a second internal watcher to cache the getter value.
+"Track-only" pattern example:
+
+```js
+const data = store({
+    a: 0,
+    b: 0,
+    c: 0,
+})
+
+// watch only "a" and "b" props
+watch(() => [
+   data.a,
+   data.b,
+], () => {
+    console.log(data.a)
+    console.log(data.b)
+    console.log(data.c)
+})
+
+data.a++ // trigger watch update
+data.b++ // trigger watch update
+data.c++ // doesn't trigger watch update
+```
 
 </details>
 
@@ -218,8 +249,8 @@ When a reactive function is set as attribute value or child, it is invoked only
 
 Each constructed tag has 3 additional optional lifecycle attributes:
 
-- `onmount: func` - optional callback called when the element is inserted in the DOM
-- `onunmount: func` - optional callback called when the element is removed from the DOM
+- `onmount: func(el)` - optional callback called when the element is inserted in the DOM
+- `onunmount: func(el)` - optional callback called when the element is removed from the DOM
 - `rid: any` - "replacement id" is an identifier based on which we can decide whether to reuse the element or not during rerendering (e.g. on list change); the value could be anything comparable with `==`
 
 </details>

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "0.0.1-rc.2",
+    "version": "0.0.1-rc.4",
     "name": "shablon",
     "description": "No-build JavaScript framework for Single-page applications",
     "author": "Gani Georgiev",
@@ -24,7 +24,7 @@
     "devDependencies": {
         "jsdom": "^26.0.0",
         "prettier": "^3.6.2",
-        "rolldown": "^1.0.0-beta.44"
+        "rolldown": "^1.0.0-beta.50"
     },
     "prettier": {
         "tabWidth": 4,

package/src/router.js

@@ -43,12 +43,16 @@ export function router(routes, options = { fallbackPath: "#/", transition: true
     let prevDestroy;
 
     let onHashChange = () => {
-        let path = window.location.hash || options.fallbackPath;
+        let path = window.location.hash;
 
-        let route =
-            findActiveRoute(defs, path) || findActiveRoute(defs, options.fallbackPath);
+        let route = findActiveRoute(defs, path);
         if (!route) {
-            console.warn("no route found");
+            if (options.fallbackPath != path) {
+                window.location.hash = options.fallbackPath;
+                return
+            }
+
+            console.warn("missing route:", path);
             return;
         }
 
@@ -57,7 +61,7 @@ export function router(routes, options = { fallbackPath: "#/", transition: true
                 await prevDestroy?.();
                 prevDestroy = await route.handler(route);
             } catch (err) {
-                console.warn("Route navigation failed:", err);
+                console.warn("route navigation failed:", err);
             }
         };
 
@@ -116,7 +120,7 @@ function prepareRoutes(routes) {
                 parts[i].endsWith("}")
             ) {
                 // param
-                parts[i] = "(?<" + parts[i].substring(1, parts[i].length - 1) + ">\\w+)";
+                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,6 +7,7 @@ let cleanTimeoutId;
 
 let idSym = Symbol();
 let parentSym = Symbol();
+let pathsResetedSym = Symbol();
 let childrenSym = Symbol();
 let pathsSubsSym = Symbol();
 let unwatchedSym = Symbol();
@@ -14,11 +15,15 @@ let onRemoveSym = Symbol();
 
 /**
  * Watch registers a callback function that fires on initialization and
- * every time any of its `store` reactive dependencies changes.
+ * every time any of its evaluated `store` reactive properties change.
  *
- * Returns a "watcher" object that could be used to `unwatch()` the registered listener.
+ * It returns a "watcher" object that could be used to `unwatch()` the registered listener.
  *
- * Example:
+ * Optionally also accepts a second callback function that is excluded from the evaluated
+ * store props tracking and instead is invoked only when `trackedFunc` is called
+ * (could be used as a "track-only" watch pattern).
+ *
+ * Simple example:
  *
  * ```js
  * const data = store({ count: 0 })
@@ -32,19 +37,47 @@ let onRemoveSym = Symbol();
  * data.count++ // doesn't trigger watch update
  * ```
  *
- * @param  {Function} callback
+ * "Track-only" example:
+ *
+ * ```js
+ * const data = store({
+ *     a: 0,
+ *     b: 0,
+ *     c: 0,
+ * })
+ *
+ * // watch only "a" and "b" props
+ * watch(() => [
+ *    data.a,
+ *    data.b,
+ * ], () => {
+ *     console.log(data.a)
+ *     console.log(data.b)
+ *     console.log(data.c)
+ * })
+ *
+ * data.a++ // trigger watch update
+ * data.b++ // trigger watch update
+ * data.c++ // doesn't trigger watch update
+ * ```
+ *
+ * @param {Function} trackedFunc
+ * @param {Function} [optUntrackedFunc]
  * @return {{unwatch:Function, last:any, run:Function}}
  */
-export function watch(callback) {
+export function watch(trackedFunc, optUntrackedFunc) {
     let watcher = {
         [idSym]: "_" + Math.random(),
-    };
+    }
 
     allWatchers.set(watcher[idSym], watcher);
 
     watcher.run = () => {
+        let oldActiveWatcher;
+
         // nested watcher -> register previous watcher as parent
         if (activeWatcher) {
+            oldActiveWatcher = activeWatcher
             watcher[parentSym] = activeWatcher[idSym];
 
             // store immediate children references for quicker cleanup
@@ -53,8 +86,14 @@ export function watch(callback) {
         }
 
         activeWatcher = watcher;
-        watcher.last = callback();
-        activeWatcher = allWatchers.get([watcher[parentSym]]); // restore parent ref (if any)
+        activeWatcher[pathsResetedSym] = false;
+        watcher.last = trackedFunc();
+
+        activeWatcher = null;
+        optUntrackedFunc?.();
+
+        // restore original ref (if any)
+        activeWatcher = oldActiveWatcher;
     };
 
     watcher.unwatch = function () {
@@ -126,7 +165,7 @@ function removeWatcher(id) {
  * Getters are also supported out of the box and they are invoked every
  * time when any of their dependencies change.
  * If a getter is used in a reactive function, its resulting value is cached,
- * aka. if the final value hasn't changed it will not trigger an unnecessery reactive update.
+ * aka. if the final value hasn't changed it will not trigger an unnecessary reactive update.
  *
  * Multiple changes from one or many stores are also automatically batched in a microtask.
  *
@@ -148,6 +187,10 @@ function createProxy(obj, pathWatcherIds) {
 
     let handler = {
         get(obj, prop, target) {
+            if (prop === "__raw") {
+                return obj;
+            }
+
             // getter?
             let getterProp;
             if (descriptors[prop]?.get) {
@@ -164,19 +207,21 @@ function createProxy(obj, pathWatcherIds) {
                 prop = "@" + prop;
             }
 
+            const propVal = obj[prop]
+
             // directly return symbols and functions (pop, push, etc.)
-            if (typeof prop == "symbol" || typeof obj[prop] == "function") {
-                return obj[prop];
+            if (typeof prop == "symbol" || typeof propVal == "function") {
+                return propVal;
             }
 
             // wrap child object or array as sub store
             if (
-                typeof obj[prop] == "object" &&
-                obj[prop] !== null &&
-                !obj[prop][parentSym]
+                propVal !== null && typeof propVal == "object" &&
+                !propVal[parentSym] &&
+                !isExcludedInstance(propVal)
             ) {
-                obj[prop][parentSym] = [obj, prop];
-                obj[prop] = createProxy(obj[prop], pathWatcherIds);
+                propVal[parentSym] = [obj, prop];
+                obj[prop] = createProxy(propVal, pathWatcherIds);
             }
 
             // register watch subscriber (if any)
@@ -184,6 +229,42 @@ function createProxy(obj, pathWatcherIds) {
                 let currentPath = getPath(obj, prop);
                 let activeWatcherId = activeWatcher[idSym];
 
+                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;
+                }
+
                 let subs = pathWatcherIds.get(currentPath);
                 if (!subs) {
                     subs = new Set();
@@ -191,7 +272,6 @@ function createProxy(obj, pathWatcherIds) {
                 }
                 subs.add(activeWatcherId);
 
-                activeWatcher[pathsSubsSym] = activeWatcher[pathsSubsSym] || new Set();
                 activeWatcher[pathsSubsSym].add(subs);
 
                 // register a child watcher to update the custom getter prop replacement
@@ -264,6 +344,17 @@ function getPath(obj, prop) {
     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

@@ -61,7 +61,7 @@ function initMutationObserver() {
     function recursiveObserveCall(method, nodes) {
         for (let n of nodes) {
             if (n[method]) {
-                n[method]();
+                n[method](n);
             }
             if (n.childNodes) {
                 recursiveObserveCall(method, n.childNodes);
@@ -116,9 +116,9 @@ function tag(tagName, attrs = {}, ...children) {
                     }
 
                     if (useSetAttr) {
-                        el.setAttribute(attr, val());
+                        el.setAttribute(attr, val(el));
                     } else {
-                        el[attr] = val();
+                        el[attr] = val(el);
                     }
                 });
             }
@@ -140,7 +140,7 @@ function tag(tagName, attrs = {}, ...children) {
             }
         }
 
-        customMount?.();
+        customMount?.(el);
     };
 
     let customUnmount = el.onunmount;
@@ -165,7 +165,7 @@ function tag(tagName, attrs = {}, ...children) {
         }
         el[cleanupFuncsSym] = null;
 
-        customUnmount?.();
+        customUnmount?.(el);
     };
 
     setChildren(el, children);
@@ -177,14 +177,17 @@ function setChildren(el, children) {
     children = toArray(children);
 
     for (let childOrFunc of children) {
-        if (Array.isArray(childOrFunc)) {
-            // nested array
-            setChildren(el, childOrFunc);
-        } else if (typeof childOrFunc == "function") {
+        if (typeof childOrFunc == "function") {
             initChildrenFuncWatcher(el, childOrFunc);
         } else {
-            // plain elem
-            el.appendChild(normalizeNode(childOrFunc));
+            let normalized = normalizeNode(childOrFunc);
+            if (Array.isArray(normalized)) {
+                // nested array
+                setChildren(el, normalized);
+            } else if (normalized) {
+                // plain elem
+                el.appendChild(normalized);
+            }
         }
     }
 }
@@ -211,7 +214,7 @@ function initChildrenFuncWatcher(el, childrenFunc) {
             return;
         }
 
-        let newChildren = toArray(childrenFunc());
+        let newChildren = toArray(childrenFunc(el));
         let totalNewLength = newChildren.length;
         let newKeysMap = new Map();
 
@@ -395,11 +398,16 @@ 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") {
+    if (typeof child == "string" || typeof child == "number" || typeof child == "boolean") {
         let childNode = document.createTextNode(child);
         childNode.rid = child;
         return childNode;
     }
 
+    // in case child is DOM Proxy element/array loaded from a store object
+    if (typeof child?.__raw != "undefined") {
+        return child.__raw
+    }
+
     return child;
 }