@bitstillery/mithril 3.1.2 → 3.3.0

package/README.md

@@ -1,24 +1,22 @@
-# @bitstillery/mithril
+# Mithril Bitstillery
 
-Mithril.js fork with fine-grained reactivity, SSR hydration, and built-in signals. Drop-in compatible with Mithril v2.x.
+Mithril Bitstillery extends Mithril with integrated state management, SSR hydration, watchers, and a signal/proxy store. Drop-in compatible with Mithril v2.x.
 
 ```bash
 bun add @bitstillery/mithril
 ```
 
-## Why
+## Strengths
 
-Mithril.js uses global `m.redraw()` — one state change re-renders **everything**. This fork adds component-level reactivity via signals so only affected components update.
+Mithril Bitstillery focuses on **state management**, **SSR**, **watchers**, and **developer experience** around its signal/proxy store:
 
-| Feature          | Original            | This Fork                        |
-| ---------------- | ------------------- | -------------------------------- |
-| Reactivity       | Global `m.redraw()` | Fine-grained component updates   |
-| State Management | Manual redraw calls | Signals with automatic tracking  |
-| SSR              | No hydration        | State serialization + hydration  |
-| TypeScript       | Community types     | Native                           |
-| Stream / request | Built-in            | Removed (use signals, `fetch()`) |
-
-Signals are opt-in. Existing Mithril code works unchanged.
+| Feature          | Description                                                         |
+| ---------------- | ------------------------------------------------------------------- |
+| Proxy State      | Reactive objects with nested objects, arrays, computeds             |
+| State Management | `state()` + `Store` for persistence (localStorage, session)         |
+| SSR              | Full server-side rendering with state serialization + hydration     |
+| Watchers         | `watch()` for observing signal changes; `effect()` for side effects |
+| DX               | Automatic dependency tracking, no manual redraw for signals         |
 
 **Docs**: [mithril.garage44.org](https://mithril.garage44.org)
 
@@ -38,7 +36,7 @@ count(5) // Logs: 5 × 2 = 10
 
 ## Proxy State
 
-Wraps signals in a proxy for ergonomic access. Components automatically track which properties they read and only re-render when those change.
+`state()` creates reactive objects. Components track which properties they read and only re-render when those change.
 
 ```tsx
 import m, {state, MithrilComponent} from '@bitstillery/mithril'
@@ -61,6 +59,19 @@ m.mount(document.body, Counter)
 
 The second argument to `state()` is a name used for SSR serialization.
 
+## Watchers
+
+`watch()` observes signal changes:
+
+```typescript
+import {state, watch} from '@bitstillery/mithril'
+
+const $s = state({count: 0}, 'app')
+const unwatch = watch($s.$count, (newVal, oldVal) => console.log(`${oldVal} → ${newVal}`))
+$s.count++ // triggers callback
+unwatch() // stop observing
+```
+
 ## SSR Hydration
 
 ```typescript

package/api/router.ts

@@ -29,7 +29,7 @@ export type SSRResult = string | {html: string; state: SSRState}
 export interface Route {
     (path: string, params?: Record<string, any>, shouldReplaceHistory?: boolean): void
     (path: string, component: ComponentType, shouldReplaceHistory?: boolean): void
-    set: (path: string, params?: Record<string, any>, data?: any) => void
+    set: (path: string, params?: Record<string, any>, data?: any) => Promise<void>
     get: () => string
     prefix: string
     link: (vnode: VnodeType) => string
@@ -53,6 +53,8 @@ interface MountRedraw {
 }
 
 interface RouteOptions {
+    /** When true, forces the route component to remount (e.g. for same-route navigation with different query params) */
+    remount?: boolean
     replace?: boolean
     state?: any
     title?: string | null
@@ -77,6 +79,9 @@ export default function router($window: any, mountRedraw: MountRedraw) {
     let attrs: Record<string, any> = {}
     let currentPath: string | undefined
     let lastUpdate: ((comp: any) => void) | null = null
+    let routeSetResolve: (() => void) | null = null
+    let remountPath: string | null = null
+    let pendingRemount = false
 
     const RouterRoot: ComponentType = {
         onremove: function () {
@@ -89,11 +94,22 @@ export default function router($window: any, mountRedraw: MountRedraw) {
             // if (!hasBeenResolved) return
 
             // Pass currentPath in attrs so RouteResolver.render can use it for routePath.
-            // Use attrs.key (not currentPath) so that route param changes within the same
-            // route pattern update the component instead of causing a full remount.
+            // Use remountPath when set (from route.set with remount: true) to force remount
+            // for same-route navigation; otherwise attrs.key for route param changes.
             const routeAttrs = {...attrs, routePath: currentPath || attrs.routePath}
-            const vnode = Vnode(component, attrs.key, routeAttrs, null, null, null)
-            if (currentResolver) return currentResolver.render!(vnode as any)
+            const vnodeKey = remountPath ?? attrs.key
+            const vnode = Vnode(component, vnodeKey, routeAttrs, null, null, null)
+            if (currentResolver) {
+                const result = currentResolver.render!(vnode as any)
+                // When remount requested, wrap in keyed fragment so same-route navigation
+                // (e.g. Stock <-> TBO) forces full remount. Key must change when path changes.
+                // Always wrap when we have a path so structure is consistent; key drives remount.
+                const fragmentKey = remountPath ?? currentPath ?? undefined
+                if (remountPath && fragmentKey != null) {
+                    return hyperscript.fragment({key: fragmentKey}, result)
+                }
+                return result
+            }
             // Wrap in a fragment to preserve existing key semantics
             return [vnode]
         },
@@ -176,7 +192,9 @@ export default function router($window: any, mountRedraw: MountRedraw) {
 
         function reject(e: any) {
             console.error(e)
-            route.set(fallbackRoute!, null, {replace: true})
+            const resolve = routeSetResolve
+            routeSetResolve = null
+            route.set(fallbackRoute!, null, {replace: true}).then(() => resolve?.())
         }
 
         loop(0)
@@ -206,8 +224,10 @@ export default function router($window: any, mountRedraw: MountRedraw) {
                         if (isRedirect(comp)) {
                             // Extract redirect target path
                             const redirectPath = comp[REDIRECT]
-                            // Trigger navigation to redirect target
-                            route.set(redirectPath, null)
+                            const resolve = routeSetResolve
+                            routeSetResolve = null
+                            // Trigger navigation to redirect target; resolve original Promise when redirect completes
+                            route.set(redirectPath, null).then(() => resolve?.())
                             // Skip rendering current route - new route resolution will handle redirect target
                             return
                         }
@@ -228,7 +248,13 @@ export default function router($window: any, mountRedraw: MountRedraw) {
                         }
                         attrs = data.params
                         currentPath = path
+                        if (pendingRemount) {
+                            remountPath = path
+                            pendingRemount = false
+                        }
                         lastUpdate = null
+                        routeSetResolve?.()
+                        routeSetResolve = null
                         if (hasBeenResolved) mountRedraw.redraw()
                         else {
                             hasBeenResolved = true
@@ -255,7 +281,9 @@ export default function router($window: any, mountRedraw: MountRedraw) {
             if (path === fallbackRoute) {
                 throw new Error('Could not resolve default route ' + fallbackRoute + '.')
             }
-            route.set(fallbackRoute!, null, {replace: true})
+            const resolve = routeSetResolve
+            routeSetResolve = null
+            route.set(fallbackRoute!, null, {replace: true}).then(() => resolve?.())
         }
     }
 
@@ -304,32 +332,39 @@ export default function router($window: any, mountRedraw: MountRedraw) {
         // The RouterRoot component is mounted when the route is first resolved.
         resolveRoute()
     }
-    route.set = function (path: string, data: Record<string, any> | null, options?: RouteOptions) {
+    route.set = function (path: string, data: Record<string, any> | null, options?: RouteOptions): Promise<void> {
         if (lastUpdate != null) {
             options = options || {}
             options.replace = true
         }
         lastUpdate = null
 
+        if (!options?.remount) {
+            remountPath = null
+        }
+        pendingRemount = options?.remount ?? false
+
         path = buildPathname(path, data || {})
-        if (ready) {
-            // Router is initialized - use history API for navigation
-            const state = options ? options.state : null
-            const title = options ? options.title : null
-            if ($window?.history) {
-                if (options && options.replace) $window.history.replaceState(state, title, route.prefix + path)
-                else $window.history.pushState(state, title, route.prefix + path)
-            }
-            // Update URL before fireAsync so resolveRoute reads the new path
-            fireAsync()
-            // In SSR context (no $window), navigation is a no-op since we're just rendering HTML
-        } else {
-            // Router not yet initialized - use location.href for initial navigation
+        if (!ready || !$window) {
+            // Router not yet initialized or SSR - navigation is a no-op
             if ($window?.location) {
                 $window.location.href = route.prefix + path
             }
-            // In SSR context (no $window), this is a no-op since we're just rendering HTML
+            return Promise.resolve()
         }
+        // Router is initialized - use history API for navigation
+        const state = options ? options.state : null
+        const title = options ? options.title : null
+        if ($window.history) {
+            if (options && options.replace) $window.history.replaceState(state, title, route.prefix + path)
+            else $window.history.pushState(state, title, route.prefix + path)
+        }
+        const promise = new Promise<void>((resolve) => {
+            routeSetResolve = resolve
+        })
+        // Update URL before fireAsync so resolveRoute reads the new path
+        fireAsync()
+        return promise
     }
     route.get = function (): string {
         // If currentPath is not set (e.g., during SSR before route.resolve is called),
@@ -352,11 +387,12 @@ export default function router($window: any, mountRedraw: MountRedraw) {
             // let them be specified in the selector as well.
             const child = hyperscript(
                 vnode.attrs?.selector || 'a',
-                censor(vnode.attrs || {}, ['options', 'params', 'selector', 'onclick']),
+                censor(vnode.attrs || {}, ['options', 'params', 'selector', 'onclick', 'onafternavigate']),
                 vnode.children,
             )
             let options: RouteOptions | undefined
             let onclick: any
+            let onafternavigate: (() => void) | undefined
             let href: string
 
             // Let's provide a *right* way to disable a route link, rather than
@@ -373,6 +409,7 @@ export default function router($window: any, mountRedraw: MountRedraw) {
             } else {
                 options = vnode.attrs?.options
                 onclick = vnode.attrs?.onclick
+                onafternavigate = vnode.attrs?.onafternavigate
                 // Easier to build it now to keep it isomorphic.
                 href = buildPathname(child.attrs!.href || '', vnode.attrs?.params || {})
                 // Make Link isomorphic - use empty prefix on server for pathname routing
@@ -421,7 +458,7 @@ export default function router($window: any, mountRedraw: MountRedraw) {
                             e.originalEvent.preventDefault()
                         }
                         ;(e as any).redraw = false
-                        route.set(href, null, options)
+                        route.set(href, null, options).then(onafternavigate ?? (() => {}))
                     }
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bitstillery/mithril",
-    "version": "3.1.2",
+    "version": "3.3.0",
     "description": "Mithril + Signals, Store and SSR",
     "license": "MIT",
     "author": "Bitstillery",
@@ -56,10 +56,11 @@
         "test": "bun test",
         "prepublishOnly": "bun run lint:ts",
         "pack:dry-run": "npm pack --dry-run",
-        "release": "standard-version && npm publish",
-        "release:patch": "standard-version --release-as patch && npm publish",
-        "release:minor": "standard-version --release-as minor && npm publish",
-        "release:major": "standard-version --release-as major && npm publish"
+        "publish": "./scripts/release.sh",
+        "release": "./scripts/release.sh",
+        "release:patch": "./scripts/release.sh --release-as patch",
+        "release:minor": "./scripts/release.sh --release-as minor",
+        "release:major": "./scripts/release.sh --release-as major"
     },
     "dependencies": {
         "htm": "^3.1.1"

package/signal.ts

@@ -100,32 +100,40 @@ export class Signal<T> {
     set value(newValue: T) {
         if (this._value !== newValue) {
             this._value = newValue
-            // Ensure _subscribers is initialized (defensive check)
-            if (!this._subscribers) {
-                this._subscribers = new Set()
-            }
-            // Notify all subscribers
-            const context = getSSRContext()
-            this._subscribers.forEach((fn) => {
-                try {
-                    // Always run watchers - wrap in SSR context if available
-                    if (context) {
-                        // Run watcher inside SSR context, similar to events
-                        runWithContext(context, () => {
-                            fn()
-                        })
-                    } else {
+            this.trigger()
+        }
+    }
+
+    /**
+     * Notify subscribers and trigger redraws without changing the value.
+     * Use when the value is an object/array that was mutated in place (e.g. keys added/removed).
+     */
+    trigger(): void {
+        // Ensure _subscribers is initialized (defensive check)
+        if (!this._subscribers) {
+            this._subscribers = new Set()
+        }
+        // Notify all subscribers
+        const context = getSSRContext()
+        this._subscribers.forEach((fn) => {
+            try {
+                // Always run watchers - wrap in SSR context if available
+                if (context) {
+                    // Run watcher inside SSR context, similar to events
+                    runWithContext(context, () => {
                         fn()
-                    }
-                } catch (e) {
-                    console.error('Error in signal subscriber:', e)
+                    })
+                } else {
+                    fn()
                 }
-            })
-            // Trigger component redraws for affected components
-            // This is set up in index.ts after m.redraw is created
-            if ((signal as any).__redrawCallback) {
-                ;(signal as any).__redrawCallback(this)
+            } catch (e) {
+                console.error('Error in signal subscriber:', e)
             }
+        })
+        // Trigger component redraws for affected components
+        // This is set up in index.ts after m.redraw is created
+        if ((signal as any).__redrawCallback) {
+            ;(signal as any).__redrawCallback(this)
         }
     }
 

package/state.ts

@@ -211,6 +211,9 @@ export function state<T extends Record<string, any>>(initial: T, name?: string,
                 ;(value as any)._parentSignal = sig as Signal<any>
             } else if (Array.isArray(value)) {
                 arrayParentSignalMap.set(value, sig as Signal<any>)
+            } else if ((value as any).__isState === true) {
+                // Nested object proxies: notify parent when keys are added/removed
+                arrayParentSignalMap.set(value, sig as Signal<any>)
             }
         }
 
@@ -738,8 +741,13 @@ export function state<T extends Record<string, any>>(initial: T, name?: string,
                         nestedSignalMap.set(key, createPropertySignal(value))
                     }
                 } else {
-                    // Create new signal
+                    // Create new signal (new key added to object)
                     nestedSignalMap.set(key, createPropertySignal(value))
+                    // Notify parent so subscribers see the key addition
+                    const parentSignal = arrayParentSignalMap.get(wrapped) || (wrapped as any)._parentSignal
+                    if (parentSignal && typeof (parentSignal as any).trigger === 'function') {
+                        ;(parentSignal as Signal<any>).trigger()
+                    }
                 }
 
                 return true
@@ -794,6 +802,11 @@ export function state<T extends Record<string, any>>(initial: T, name?: string,
                     }
                     // Remove from the signal map
                     nestedSignalMap.delete(key)
+                    // Notify parent so subscribers see the key removal
+                    const parentSignal = arrayParentSignalMap.get(wrapped) || (wrapped as any)._parentSignal
+                    if (parentSignal && typeof (parentSignal as any).trigger === 'function') {
+                        ;(parentSignal as Signal<any>).trigger()
+                    }
                 }
 
                 // Delete from target