fusee-framework 1.4.1 → 1.5.0

package/README.md

@@ -1,5 +1,5 @@
 # Fusée Framework 🚀
-**v1.4.1 — Signals-First JS Framework | Atomic Reactivity | Peak Performance**
+**v1.5.0 — Signals-First JS Framework | Atomic Reactivity | Peak Performance**
 
 Fusée is a custom, high-performance fine-grained reactive JavaScript framework built for speed and simplicity. It features a recursive, non-greedy compiler, a signals-based reactivity engine, Dependency Injection for components and a comprehensive CLI for instant application scaffolding.
 
@@ -76,10 +76,28 @@ export const Welcome = defineComponent({
 
 ---
 
+## ✅ Quality Assurance & Testing
+
+Fusée is built with a test-driven mindset to ensure the reliability of its reactivity engine and component lifecycle.
+
+- **Total Tests:** `200`
+- **Status:** `All Passed`
+- **Framework:** [Vitest](https://vitest.dev/)
+- **Environment:** JSDOM (Browser simulation)
+
+### Test Coverage includes:
+*   **Reactivity Engine:** 100% (Signals, Batching, Computed, Watchers).
+*   **Component System:** Props, Slots, Async Components, and Lifecycle Hooks.
+*   **Dependency Injection:** Nested Provide/Inject and Shadowing.
+*   **Directives:** `f-if`, `f-for`, `f-model`, and Event Modifiers.
+*   **Memory Safety:** Explicit checks for memory leaks and automatic effect disposal.
+
+---
+
 ## 🚀 Future Roadmap
 
-- [ ] Global Store Management
-- [ ] Advanced file-based routing support
-- [ ] Integrated lightweight compiler which transforms declarative HTML into optimized runtime instructions
+- [ ] Advanced file-based routing support and state management
+- [ ] Lightweight compiler which transforms declarative HTML into optimized runtime instructions
+- [ ] Integrated backend development support
 
 Built with ❤️ by me, Sebi Somu, a forward-thinking JavaScript Architect.

package/app/routes/TestFor.js

@@ -6,10 +6,8 @@ export const TestFor = defineComponent({
             { id: 3, name: 'Item 3' }
         ])
         const search = signal('')
-        
-        // ✨ NEW: Using the reactive .filter() method on the signal!
-        // This returns a Computed signal that updates automatically.
-        const filteredItems = items.filter(item => 
+
+        const filteredItems = items.filter(item =>
             item.name.toLowerCase().includes(search().toLowerCase())
         )
 
@@ -19,11 +17,9 @@ export const TestFor = defineComponent({
             items,
             search,
             filteredItems,
-            // 🔗 Chaining test: filter -> map -> join
             namesSummary: filteredItems.map(i => i.name).join(', '),
 
             updateItem: (id, newName) => {
-                // We update the SOURCE signal so the .filter() can see the new values!
                 items(items().map(i => i.id === id ? { ...i, name: newName } : i))
             },
             addItem: () => {

package/auto-imports.d.ts

@@ -9,6 +9,7 @@ declare global {
   const batch: typeof import('fusee-framework').batch
   const computed: typeof import('fusee-framework').computed
   const defineComponent: typeof import('fusee-framework').defineComponent
+  const defineStore: typeof import('fusee-framework').defineStore
   const directive: typeof import('fusee-framework').directive
   const effect: typeof import('fusee-framework').effect
   const emit: typeof import('fusee-framework').emit
@@ -21,4 +22,6 @@ declare global {
   const provide: typeof import('fusee-framework').provide
   const signal: typeof import('fusee-framework').signal
   const untrack: typeof import('fusee-framework').untrack
+  const watch: typeof import('fusee-framework').watch
+  const watchEffect: typeof import('fusee-framework').watchEffect
 }

package/framework/auto-import-preset.js

@@ -1,6 +1,6 @@
 export const FuseePreset = {
     'fusee-framework': [
-        'signal', 'computed', 'effect',
+        'signal', 'computed', 'effect', 'watch', 'watchEffect',
         'batch', 'untrack', 'inspect',
         'defineComponent', 'onMount', 'onUnmount',
         'directive',

package/framework/core/component.js

@@ -11,6 +11,10 @@ export function getCurrentInstance() {
     return currentInstance
 }
 
+export function setCurrentInstance(instance) {
+    currentInstance = instance
+}
+
 function resolveProps(schema, received) {
     const isArray = Array.isArray(schema)
     const resolved = {}
@@ -139,6 +143,7 @@ export function defineComponent(options) {
 
         currentInstance = instance
         const result = options.setup(instance.props, { emit, slots })
+        instance.state = result
         result._instance = instance
         currentInstance = null
 

package/framework/core/signal.js

@@ -59,17 +59,33 @@ export function signal(initialValue) {
 }
 
 export function effect(fn) {
+    let active = true
+    let running = false
+
     const run = () => {
+        if (!active || running) {
+            if (running) console.warn('[framework] Recursive effect detected')
+            return
+        }
+
+        running = true
         for (const dep of run.deps) dep.delete(run)
         run.deps.clear()
 
+        const prevEffect = currentEffect
         currentEffect = run
         try { fn() }
-        finally { currentEffect = null }
+        finally {
+            currentEffect = prevEffect
+            running = false
+        }
     }
 
     run.deps = new Set()
+
     const cleanup = () => {
+        active = false
+        pendingEffects.delete(run)
         for (const dep of run.deps) dep.delete(run)
         run.deps.clear()
     }
@@ -83,53 +99,80 @@ export function effect(fn) {
 export function computed(fn) {
     let value
     let dirty = true
+    let active = true
     const subscribers = new Set()
+    const deps = new Set()
 
     const computedNode = () => {
-        if (!dirty) {
+        if (!active || dirty) return
+
+        if (subscribers.size > 0) {
+            if (!runRecompute()) return
+        } else {
             dirty = true
-            for (const dep of computedNode.deps) dep.delete(computedNode)
-            computedNode.deps.clear()
-            for (const sub of [...subscribers]) scheduleEffect(sub)
+            for (const d of deps) d.delete(computedNode)
+            deps.clear()
+            return
         }
+
+        for (const sub of [...subscribers]) scheduleEffect(sub)
     }
 
-    computedNode.deps = new Set()
+    computedNode.deps = deps
+
+    let computing = false
+
+    function runRecompute() {
+        if (computing) {
+            console.warn('[framework] Circular dependency detected in computed()')
+            return false
+        }
+        
+        computing = true
+        for (const d of deps) d.delete(computedNode)
+        deps.clear()
+
+        const prevEffect = currentEffect
+        currentEffect = active ? computedNode : null
+        try {
+            const newValue = fn()
+            const changed = !Object.is(newValue, value)
+            value = newValue
+            dirty = false
+            return changed
+        } finally {
+            currentEffect = prevEffect
+            computing = false
+        }
+    }
 
     function accessor() {
         if (arguments.length === 0) {
-            if (currentEffect) {
+            if (active && currentEffect) {
                 subscribers.add(currentEffect)
                 currentEffect.deps.add(subscribers)
             }
+
             if (dirty) {
-                for (const dep of computedNode.deps) dep.delete(computedNode)
-                computedNode.deps.clear()
-
-                const prevEffect = currentEffect
-                currentEffect = computedNode
-                try {
-                    const newValue = fn()
-                    if (newValue !== value) value = newValue
-                } finally {
-                    currentEffect = prevEffect
-                    dirty = false
-                }
+                runRecompute()
             }
+
             return value
         }
         console.warn('[framework] computed() is read-only')
     }
 
     accessor.dispose = () => {
-        for (const dep of computedNode.deps) dep.delete(computedNode)
-        computedNode.deps.clear()
+        active = false
+        dirty = true
+        pendingEffects.delete(computedNode)
+        for (const d of deps) d.delete(computedNode)
+        deps.clear()
         subscribers.clear()
     }
 
     accessor.isSignal = true
     accessor.readonly = true
-
     addReactiveArrayMethods(accessor)
 
     return accessor
@@ -145,6 +188,82 @@ export function untrack(fn) {
     }
 }
 
+export function watch(source, callback, options = {}) {
+    if (typeof callback !== 'function') {
+        console.warn('[framework] watch() callback must be a function')
+        return () => { }
+    }
+
+    const { immediate = false, equals = Object.is } = options
+    const { getter, isMultiSource } = normalizeWatchSource(source)
+
+    let initialized = false
+    let oldValue
+    const cleanupRef = { fn: null }
+
+    const onCleanup = (fn) => {
+        if (typeof fn !== 'function') {
+            console.warn('[framework] onCleanup() expects a function')
+            return
+        }
+        cleanupRef.fn = fn
+    }
+
+    const stopEffect = effect(() => {
+        const newValue = getter()
+
+        if (!initialized) {
+            initialized = true
+            oldValue = cloneWatchValue(newValue, isMultiSource)
+            if (immediate) {
+                untrack(() => callback(newValue, undefined, onCleanup))
+            }
+            return
+        }
+
+        if (!hasWatchChanged(newValue, oldValue, isMultiSource, equals)) {
+            return
+        }
+
+        const previousValue = oldValue
+        oldValue = cloneWatchValue(newValue, isMultiSource)
+
+        runWatchCleanup(cleanupRef)
+        untrack(() => callback(newValue, previousValue, onCleanup))
+    })
+
+    return () => {
+        stopEffect()
+        runWatchCleanup(cleanupRef)
+    }
+}
+
+export function watchEffect(fn) {
+    if (typeof fn !== 'function') {
+        console.warn('[framework] watchEffect() expects a function')
+        return () => { }
+    }
+
+    const cleanupRef = { fn: null }
+    const onCleanup = (cleanup) => {
+        if (typeof cleanup !== 'function') {
+            console.warn('[framework] onCleanup() expects a function')
+            return
+        }
+        cleanupRef.fn = cleanup
+    }
+
+    const stopEffect = effect(() => {
+        runWatchCleanup(cleanupRef)
+        fn(onCleanup)
+    })
+
+    return () => {
+        stopEffect()
+        runWatchCleanup(cleanupRef)
+    }
+}
+
 export function inspect(...args) {
     const isDev = typeof import.meta.env !== 'undefined' ? !!import.meta.env.DEV : true
     if (!isDev) return
@@ -244,3 +363,48 @@ function addMutatingArrayMethods(accessor) {
         return accessor
     }
 }
+
+// Helpers for watch/watchEffect
+function normalizeWatchSource(source) {
+    if (Array.isArray(source)) {
+        const getters = source.map(normalizeSingleWatchSource)
+        return {
+            getter: () => getters.map(get => get()),
+            isMultiSource: true
+        }
+    }
+    return {
+        getter: normalizeSingleWatchSource(source),
+        isMultiSource: false
+    }
+}
+
+function normalizeSingleWatchSource(source) {
+    if (typeof source === 'function') return source
+    console.warn('[framework] watch() source should be a signal, getter, or an array of those')
+    return () => source
+}
+
+function cloneWatchValue(value, isMultiSource) {
+    if (isMultiSource && Array.isArray(value)) return value.slice()
+    return value
+}
+
+function hasWatchChanged(newValue, oldValue, isMultiSource, equals) {
+    if (isMultiSource) {
+        if (!Array.isArray(oldValue) || newValue.length !== oldValue.length) return true
+        for (let i = 0; i < newValue.length; i++) {
+            if (!equals(newValue[i], oldValue[i])) return true
+        }
+        return false
+    }
+    return !equals(newValue, oldValue)
+}
+
+function runWatchCleanup(cleanupRef) {
+    if (typeof cleanupRef.fn === 'function') {
+        const fn = cleanupRef.fn
+        cleanupRef.fn = null
+        untrack(() => fn())
+    }
+}

package/framework/core/store.js

@@ -0,0 +1,81 @@
+import { getCurrentInstance, setCurrentInstance } from './component.js'
+
+const storesRegistry = new Map()
+const storePlugins = []
+
+export function registerStorePlugin(plugin) {
+    if (typeof plugin === 'function') {
+        storePlugins.push(plugin)
+    }
+}
+
+const isDev = typeof import.meta.env !== 'undefined' ? !!import.meta.env.DEV : true
+if (isDev && typeof window !== 'undefined') {
+    window.__FRAMEWORK_STORES__ = storesRegistry
+}
+
+export function defineStore(id, setup) {
+    if (typeof id !== 'string' || !id.trim()) {
+        console.error('[framework] defineStore requires a valid string ID.')
+    }
+
+    function useStore() {
+        let store = storesRegistry.get(id)
+
+        if (!store) {
+            const prevInstance = getCurrentInstance()
+
+            setCurrentInstance(null)
+
+            try {
+                store = setup()
+
+                if (store instanceof Promise) {
+                    console.error(`[framework] Store "${id}" cannot be async.`)
+                    throw new Error(`Async store "${id}" is not supported.`)
+                }
+
+            } catch (err) {
+                console.error(`[framework] Error initializing store "${id}":`, err)
+                throw err
+            } finally {
+                setCurrentInstance(prevInstance)
+            }
+
+            Object.defineProperties(store, {
+                $id: {
+                    value: id,
+                    enumerable: false
+                },
+                $type: {
+                    value: 'store',
+                    enumerable: false
+                }
+            })
+
+            for (const plugin of storePlugins) {
+                try {
+                    plugin(store, id)
+                } catch (e) {
+                    console.warn(`[framework] Store plugin error for "${id}":`, e)
+                }
+            }
+
+            storesRegistry.set(id, store)
+        }
+
+        return store
+    }
+
+    useStore.$id = id
+
+    return useStore
+}
+
+export function resetStore(id) {
+    storesRegistry.delete(id)
+}
+
+export function clearStores() {
+    storesRegistry.clear()
+}

package/framework/index.js

@@ -1,10 +1,11 @@
 // ─── Framework Public API ─────────────────────────────────────────────────────
-export { signal, computed, effect, batch, untrack, inspect } from './core/signal.js'
+export { signal, computed, effect, batch, untrack, inspect, watch, watchEffect } from './core/signal.js'
 export { defineComponent, defineAsyncComponent, onMount, onUnmount, parseSlots, provide, inject, getCurrentInstance } from './core/component.js'
 export { createRouter, navigate, mountOutlet } from './router/router.js'
 export { mountTemplate } from './core/compiler.js'
 
 export { defineComposable, assertSetupContext } from './core/composable.js'
+export { defineStore, resetStore, clearStores, registerStorePlugin } from './core/store.js'
 export { directive } from './core/directives.js'
 
 export const emit = () => console.warn('[framework] emit() can only be used inside component setup()')

package/framework/types/index.d.ts

@@ -4,6 +4,7 @@ export * from './composable'
 export * from './router'
 export * from './compiler'
 export * from './directives'
+export * from './store'
 
 declare global {
     type Signal<T = any> = import('./signal').Signal<T>
@@ -12,6 +13,7 @@ declare global {
     type Composable<T extends (...args: any[]) => any> = import('./composable').Composable<T>
     type DirectiveBinding<V = any> = import('./directives').DirectiveBinding<V>
     type DirectiveHooks<V = any> = import('./directives').DirectiveHooks<V>
+    const defineStore: typeof import('./store').defineStore
 }
 
 export as namespace Fusee

package/framework/types/signal.d.ts

@@ -54,12 +54,27 @@ type EffectRunner = {
     deps: Set<Set<EffectRunner>>;
 }
 
+export type WatchSource<T = any> = (() => T) | Signal<T> | Computed<T>
+export type WatchCallback<T = any> = (newValue: T, oldValue: T | undefined, onCleanup: (fn: () => void) => void) => void
+
+export interface WatchOptions {
+    immediate?: boolean;
+    equals?: (a: any, b: any) => boolean;
+}
+
 export declare function signal<T extends any[]>(initialValue: T): ArraySignalAccessor<T>
 export declare function signal<T>(initialValue: T): SignalAccessor<T>
 export declare function effect(fn: () => void): () => void
 export declare function computed<T>(fn: () => T): Computed<T>
 export declare function batch<T>(fn: () => T): T
 export declare function untrack<T>(fn: () => T): T
+export declare function watch<T>(source: WatchSource<T>, callback: WatchCallback<T>, options?: WatchOptions): () => void
+export declare function watch<T extends any[]>(
+    sources: [...{ [K in keyof T]: WatchSource<T[K]> }],
+    callback: (newValue: T, oldValue: T | undefined, onCleanup: (fn: () => void) => void) => void,
+    options?: WatchOptions
+): () => void
+export declare function watchEffect(fn: (onCleanup: (fn: () => void) => void) => void): () => void
 export declare function inspect(...args: any[]): (() => void) | void
 
 declare function setEffectHook(fn: (eff: any) => void): void

package/framework/types/store.d.ts

@@ -0,0 +1,8 @@
+export function defineStore<T>(id: string, setup: () => T): () => T;
+export function resetStore(id: string): void;
+export function clearStores(): void;
+export function registerStorePlugin(plugin: (store: any, id: string) => void): void;
+
+declare global {
+    function defineStore<T>(id: string, setup: () => T): () => T;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fusee-framework",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Fusée - Signals-first JS Framework | Peak Performance",
   "main": "framework/index.js",
   "types": "framework/types/index.d.ts",
@@ -12,7 +12,7 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest run"
   },
   "keywords": [],
   "author": "",
@@ -25,8 +25,10 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
+    "jsdom": "^29.0.2",
     "typescript": "^6.0.2",
     "unplugin-auto-import": "^21.0.0",
-    "vite": "^5.0.0"
+    "vite": "^5.0.0",
+    "vitest": "^4.1.4"
   }
-}
+}

package/vite.config.js

@@ -34,5 +34,10 @@ export default defineConfig({
                 main: path.resolve(__dirname, 'index.html'),
             }
         }
+    },
+
+    test: {
+        environment: 'jsdom',
+        globals: true
     }
 })