fusee-framework 1.5.0 → 1.5.2

package/README.md

@@ -1,5 +1,5 @@
 # Fusée Framework 🚀
-**v1.5.0 — Signals-First JS Framework | Atomic Reactivity | Peak Performance**
+**v1.5.2 — 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.
 
@@ -80,23 +80,42 @@ export const Welcome = defineComponent({
 
 Fusée is built with a test-driven mindset to ensure the reliability of its reactivity engine and component lifecycle.
 
-- **Total Tests:** `200`
+- **Total Tests:** `360`
 - **Status:** `All Passed`
 - **Framework:** [Vitest](https://vitest.dev/)
 - **Environment:** JSDOM (Browser simulation)
 
+### Running Tests
+
+```bash
+# Run all tests (easiest)
+npm test
+
+# Run all tests with verbose output
+npx vitest --reporter=verbose
+
+# Run type tests only
+npx vitest run --typecheck
+
+# Run tests in watch mode
+npx vitest
+```
+
 ### 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.
+*   **Type Safety:** Comprehensive TypeScript definitions and type tests.
+*   **Integration Tests:** Advanced module combinations and edge cases.
 
 ---
 
 ## 🚀 Future Roadmap
 
 - [ ] Advanced file-based routing support and state management
+- [ ] SSR support
 - [ ] Lightweight compiler which transforms declarative HTML into optimized runtime instructions
 - [ ] Integrated backend development support
 

package/auto-imports.d.ts

@@ -23,5 +23,4 @@ declare global {
   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', 'watch', 'watchEffect',
+        'signal', 'computed', 'effect', 'watch',
         'batch', 'untrack', 'inspect',
         'defineComponent', 'onMount', 'onUnmount',
         'directive',

package/framework/core/compiler.js

@@ -37,7 +37,6 @@ export function mountTemplate(template, container, context, components) {
     return { effects }
 }
 
-// Parses props string from component mustache into HTML attr string
 function parseComponentAttrs(propsStr) {
     let attrs = ''
     if (!propsStr || !propsStr.trim()) return attrs
@@ -49,13 +48,10 @@ function parseComponentAttrs(propsStr) {
         const attrValue = attrMatch[2]
 
         if (attrName.startsWith('@')) {
-            // Event listener: @change="handler" → data-on-change="handler"
             attrs += ` data-on-${attrName.slice(1).toLowerCase()}="${attrValue}"` 
         } else if (attrName.startsWith(':')) {
-            // Dynamic prop
             attrs += ` data-bind-prop-${attrName.slice(1).toLowerCase()}="${attrValue}"` 
         } else {
-            // Static prop
             attrs += ` data-prop-${attrName.toLowerCase()}="${attrValue}"` 
         }
     }
@@ -196,7 +192,6 @@ function bindComponents(el, components, context, effects) {
     const ComponentFn = components[name]
     if (!ComponentFn) return
 
-    // ── Props ────────────────────────────────────────────────────────────────
     const props = {}
     const listeners = {}
 
@@ -228,10 +223,7 @@ function bindComponents(el, components, context, effects) {
             }
 
         } else if (attrName.startsWith('data-on-')) {
-            // ── Emit listeners ───────────────────────────────────────────────
-            // @change="handler" → data-on-change="handler"
-            // When child emits 'change', calls context.handler(value)
-            const eventName = attrName.slice(8)  // "data-on-" → eventName
+            const eventName = attrName.slice(8)  
             const handlerExpr = attr.value.trim()
 
             listeners[eventName] = (...args) => {
@@ -239,15 +231,12 @@ function bindComponents(el, components, context, effects) {
                 if (typeof handler === 'function') {
                     handler(...args)
                 } else {
-                    // Support inline expressions: @change="count(count() + 1)"
                     evaluateExpression(handlerExpr, context)
                 }
             }
         }
     }
 
-    // ── Slots ────────────────────────────────────────────────────────────────
-    // data-slot attribute contains URI-encoded slot HTML from parent
     const rawSlot = el.getAttribute('data-slot')
     const slots = rawSlot ? parseSlots(decodeURIComponent(rawSlot)) : {}
     el.removeAttribute('data-slot')

package/framework/core/directives.js

@@ -161,7 +161,6 @@ export function processFor(el, context, components, effects) {
     const templateNode = el.cloneNode(true)
     parent.removeChild(el)
 
-    // Cache of currently rendered items: Map<key, { node, effects, context }>
     let cache = new Map()
     let previousOrder = []
 
@@ -197,7 +196,6 @@ export function processFor(el, context, components, effects) {
             let entry = cache.get(key)
 
             if (entry) {
-                // Update existing reactive signals for reused items
                 batch(() => {
                     if (typeof entry.context[itemName] === 'function' && entry.context[itemName].isSignal) {
                         entry.context[itemName](item.value)
@@ -217,7 +215,6 @@ export function processFor(el, context, components, effects) {
                 }
                 cache.delete(key)
             } else {
-                // Create new item context with signals for local state
                 const itemContext = Object.create(context)
                 itemContext[itemName] = signal(item.value)
                 if (keyName) itemContext[keyName] = signal(item.hasOwnProperty('key') ? item.key : item.rawIndex)
@@ -347,7 +344,6 @@ export function processIf(el, context, components, effects) {
 export function processIs(el, context, components, effects) {
     if (el.nodeType !== 1 || !el.hasAttribute('f-is')) return false
 
-    // 1. Prepare directive state
     const expr = el.getAttribute('f-is')
     const keepAlive = processKeepAlive(el)
 
@@ -355,8 +351,6 @@ export function processIs(el, context, components, effects) {
 
     const anchor = document.createComment('f-keepAlive-anchor')
     el.parentNode.insertBefore(anchor, el)
-
-    // Keep a clone to reuse attributes (props/@events) for every dynamic instance
     const templateNode = el.cloneNode(true)
     el.remove()
 
@@ -364,14 +358,11 @@ export function processIs(el, context, components, effects) {
     let activeKey = null
     let activeCleanup = []
 
-    // 2. Reactive loop
     effects.push(effect(() => {
         const rawValue = evaluateExpression(expr, context)
 
-        // Skip if same component is already active
         if (rawValue === activeKey) return
 
-        // 3. Handle exiting component
         if (activeKey !== null) {
             const currentEntry = cache.get(activeKey)
             if (currentEntry) {
@@ -391,15 +382,12 @@ export function processIs(el, context, components, effects) {
             return
         }
 
-        // 4. Handle entering component
         let entry = cache.get(rawValue)
 
         if (entry && keepAlive) {
-            // Restore from cache
             anchor.parentNode.insertBefore(entry.node, anchor.nextSibling)
             activeCleanup = entry.cleanup
         } else {
-            // Create new instance
             let ComponentFn = typeof rawValue === 'string' ? components[rawValue] : rawValue
 
             if (typeof ComponentFn !== 'function') {
@@ -418,7 +406,6 @@ export function processIs(el, context, components, effects) {
             const childCleanup = []
             const dynamicComponents = { ...components, [tempName]: ComponentFn }
 
-            // Trigger the internal compiler to bind props and events
             compileNode(compEl, context, dynamicComponents, childCleanup)
 
             entry = { node: compEl, cleanup: childCleanup }
@@ -429,7 +416,6 @@ export function processIs(el, context, components, effects) {
         activeKey = rawValue
     }))
 
-    // Cleanup all cached components when this directive is destroyed
     effects.push(() => {
         for (const entry of cache.values()) {
             for (const c of entry.cleanup) if (typeof c === 'function') c()
@@ -504,7 +490,7 @@ export function processEvents(el, context, effects) {
                     if (next.endsWith('ms')) return parseInt(next) || 250
                     if (next.endsWith('s')) return (parseFloat(next) || 0.25) * 1000
                 }
-                return 250 // Default
+                return 250 
             }
 
             const debounceIdx = modifiers.indexOf('debounce')
@@ -529,7 +515,6 @@ export function processEvents(el, context, effects) {
                 if (modifiers.includes('stop')) e.stopPropagation()
                 if (modifiers.includes('self') && e.target !== el) return
 
-                // Specific handling for common modifiers like .enter, .escape etc on keyboard events
                 if (e instanceof KeyboardEvent) {
                     const key = e.key.toLowerCase()
                     const keyModifiers = modifiers.filter(m => ['enter', 'escape', 'tab', 'space', 'arrowup', 'arrowdown', 'arrowleft', 'arrowright'].includes(m))
@@ -543,7 +528,6 @@ export function processEvents(el, context, effects) {
                     }
                 }
 
-                // Throttle logic (ensures execution at most once every X ms)
                 if (throttleMs > 0) {
                     const now = Date.now()
                     const remaining = throttleMs - (now - lastRun)
@@ -553,7 +537,6 @@ export function processEvents(el, context, effects) {
                         lastRun = now
                         executeLogic(e)
                     } else {
-                        // Standard throttle with trailing edge support
                         clearTimeout(throttleTimeoutId)
                         throttleTimeoutId = setTimeout(() => {
                             lastRun = Date.now()
@@ -563,7 +546,6 @@ export function processEvents(el, context, effects) {
                     return
                 }
 
-                // Debounce logic (waits for X ms of inactivity)
                 if (debounceMs > 0) {
                     clearTimeout(timeoutId)
                     timeoutId = setTimeout(() => executeLogic(e), debounceMs)

package/framework/core/evaluator.js

@@ -7,11 +7,9 @@ export function evaluateExpression(expr, context, extraContext = {}, unwrapSigna
     const keys = []
     const values = []
     
-    // Remove string literals before extracting identifiers to avoid matching words inside strings
     const exprWithoutStrings = expr.replace(/'[^']*'|"[^"]*"/g, ' ')
     const identifiers = new Set(exprWithoutStrings.match(/[a-zA-Z_$][a-zA-Z0-9_$]*/g) || [])
 
-    // Map global context (only what is used in expression)
     for (const k in context) {
         if (identifiers.has(k)) {
             keys.push(k)
@@ -20,7 +18,6 @@ export function evaluateExpression(expr, context, extraContext = {}, unwrapSigna
         }
     }
 
-    // Map extra context (like $event)
     for (const k in extraContext) {
         if (!keys.includes(k)) {
             keys.push(k)

package/framework/core/signal.js

@@ -238,32 +238,6 @@ export function watch(source, callback, options = {}) {
     }
 }
 
-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
@@ -364,7 +338,6 @@ function addMutatingArrayMethods(accessor) {
     }
 }
 
-// Helpers for watch/watchEffect
 function normalizeWatchSource(source) {
     if (Array.isArray(source)) {
         const getters = source.map(normalizeSingleWatchSource)

package/framework/index.js

@@ -1,5 +1,5 @@
 // ─── Framework Public API ─────────────────────────────────────────────────────
-export { signal, computed, effect, batch, untrack, inspect, watch, watchEffect } from './core/signal.js'
+export { signal, computed, effect, batch, untrack, inspect, watch } 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'

package/framework/types/component.d.ts

@@ -12,16 +12,10 @@ export type PropConfig = {
     required?: boolean
 }
 
-// ── Emit ──────────────────────────────────────────────────────────────────────
-// emit('change', value) — calls parent listener registered with @change="handler"
 export type EmitFn = (eventName: string, ...args: any[]) => void
 
-// ── Slots ─────────────────────────────────────────────────────────────────────
-// slots.default — default slot HTML string
-// slots.header  — named slot HTML string
 export type Slots = Record<string, string>
 
-// ── Setup context ─────────────────────────────────────────────────────────────
 export type SetupContext = {
     emit: EmitFn
     slots: Slots
@@ -42,8 +36,8 @@ export type ComponentResult = {
     [key: string]: any
 }
 
-export type ComponentOptions<TProps = ComponentProps> = {
-    props?: PropSchema
+export type ComponentOptions<TProps = ComponentProps, P = PropSchema> = {
+    props?: P
     components?: Record<string, ComponentFactory<any>>
     setup: (props: TProps, ctx: SetupContext) => ComponentResult
 }
@@ -62,13 +56,28 @@ export type ComponentApi = {
 export declare function onMount(fn: () => void): void
 export declare function onUnmount(fn: () => void): void
 export declare function parseSlots(slotHTML: string): Slots
+export declare function getCurrentInstance(): ComponentInstance | null
 
-// ── Provide / Inject ───────────────────────────────────────────────────────────
 export declare function provide<T>(key: string, value: T): void
 export declare function inject<T>(key: string): T | null
 
-export declare function defineComponent<TProps = EmptyProps>(
-    options: ComponentOptions<TProps>
+type InferPropType<T> = T extends StringConstructor ? string :
+    T extends NumberConstructor ? number :
+    T extends BooleanConstructor ? boolean :
+    any;
+
+type InferProps<P> = P extends string[]
+    ? Record<P[number], any>
+    : P extends Record<string, PropConfig>
+    ? {
+        [K in keyof P]: P[K]['required'] extends true
+        ? InferPropType<P[K]['type']>
+        : InferPropType<P[K]['type']> | (P[K] extends { default: any } ? never : undefined)
+    }
+    : Record<string, any>;
+
+export declare function defineComponent<P extends PropSchema = any, TProps = InferProps<P>>(
+    options: ComponentOptions<TProps, P>
 ): ComponentFactory<TProps>
 
 export type AsyncComponentLoader<TProps = ComponentProps> = () => Promise<ComponentFactory<TProps> | { default: ComponentFactory<TProps> } | Record<string, any>>

package/framework/types/composable.d.ts

@@ -10,5 +10,5 @@ declare global {
     }
 }
 
-export function defineComposable<T>(fn: (...args: any[]) => T): Composable<T>
-export function assertSetupContext(name?: string): any
+export declare function defineComposable<T extends (...args: any[]) => any>(fn: T): T;
+export declare function assertSetupContext(name?: string): void;

package/framework/types/evaluator.d.ts

@@ -9,7 +9,5 @@ export type InterpolationPart = {
 export const MUSTACHE_RE: RegExp
 
 export function evaluateExpression(expr: string, context: Record<string, any>, extraContext?: Record<string, any>): any
-
 export function parseInterpolation(str: string): InterpolationPart[]
-
 export function sanitizeAttr(name: string, value: string): string

package/framework/types/router.d.ts

@@ -1,5 +1,3 @@
-// ─── Router Types ─────────────────────────────────────────────────────────────
-
 import type { ComponentApi } from './component'
 
 export type Route = {

package/framework/types/signal.d.ts

@@ -1,5 +1,3 @@
-// ─── Signal Types ────────────────────────────────────────────────────────────
-
 export type SignalAccessor<T> = {
     (): T;
     (newValue: T): void;
@@ -46,8 +44,8 @@ export type ComputedAccessor<T> = {
     readonly: true;
 } & (T extends any[] ? ReactiveArrayMethods<T[number]> : {})
 
-export type Signal<T = any> = T extends any[] ? ArraySignalAccessor<T> : SignalAccessor<T>
-export type Computed<T = any> = ComputedAccessor<T>
+export type Signal<T = any> = SignalAccessor<T> & (T extends any[] ? ReactiveArrayMethods<T[number]> : {})
+export type Computed<T = any> = ComputedAccessor<T> & (T extends any[] ? ReactiveArrayMethods<T[number]> : {})
 
 type EffectRunner = {
     (): void;
@@ -74,7 +72,6 @@ export declare function watch<T extends any[]>(
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fusee-framework",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Fusée - Signals-first JS Framework | Peak Performance",
   "main": "framework/index.js",
   "types": "framework/types/index.d.ts",

package/tsconfig.json

@@ -24,6 +24,8 @@
     "declarationDir": "./dist/types",
     
     "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
     "paths": {
       "fusee-framework": ["./framework/types/index.d.ts"],
       "fusee-framework/*": ["./framework/*"]

package/vite.config.js

@@ -38,6 +38,10 @@ export default defineConfig({
 
     test: {
         environment: 'jsdom',
-        globals: true
+        globals: true,
+        typecheck: {
+            enabled: true,
+            include: ['**/*.test-d.ts'],
+        }
     }
 })