fusee-framework 1.8.0 → 1.9.1

package/README.md

@@ -1,6 +1,6 @@
 # Fusée Framework
 
-**v1.8.0 — Signals-First JS Framework | Atomic Reactivity | Peak Performance**
+**v1.9.1 — 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.
 
@@ -39,6 +39,67 @@ fusee generate page contact
 
 ---
 
+## Build-Time HTML Template Compiler (New in v1.9)
+
+Fusée now features a fully integrated **Build-Time Template Compiler** powered by the `fuseeCompilerPlugin` for Vite. Instead of parsing and compiling HTML strings at runtime, Fusée compiles external HTML templates into highly optimized virtual DOM creation calls (`h`, `hText`, `hIf`, `hFor`) during the build/dev stage.
+
+### Why use the Build-Time Compiler?
+
+- **Zero Runtime Overhead**: No template parsing in the browser, leading to smaller bundles and faster page load speeds.
+- **Separation of Concerns**: Write clean HTML in `.template.html` files with full editor autocomplete, syntax highlighting, and formatting support.
+- **Compile-Time Warnings**: Errors in template syntax are caught immediately in your terminal or browser console during development.
+
+### How to use it:
+
+1. **Create an HTML template file** (e.g., `Welcome.template.html`):
+
+```html
+<div class="card">
+  <h2>Hello, {{ name }}!</h2>
+  <input f-model="name" placeholder="Type a name..." />
+
+  <button @click="increment">Clicked {{ count }} times</button>
+
+  <p f-if="count() > 0">Double: <strong>{{ double }}</strong></p>
+</div>
+```
+
+2. **Import and bind the `render` function** in your component file (e.g., `Welcome.js`):
+
+```javascript
+import { render } from "./Welcome.template.html";
+
+export const Welcome = defineComponent({
+  render,
+  setup() {
+    const name = signal("World");
+    const count = signal(0);
+    const double = computed(() => count() * 2);
+
+    return {
+      name,
+      count,
+      double,
+      increment: () => count(count() + 1),
+    };
+  },
+});
+```
+
+Vite intercepts the `.template.html` import, runs the compiler, and inlines the generated JavaScript render code seamlessly!
+
+Benchmark results for specific stress tests (from https://github.com/codegenixdev/js-frontend-frameworks-benchmark):
+
+| Action                             | Avg Duration (ms) |
+| :--------------------------------- | :---------------- |
+| Create 50,000 Rows                 | 12.60             |
+| Update Every 10th Row (Salary +50) | 15.90             |
+| Swap 2nd and 9th-to-last Rows      | 4.60              |
+| Clear All Rows                     | 0.70              |
+| **Total Average**                  | **33.80**         |
+
+---
+
 ## Key Features
 
 - **New Go-Powered CLI**: Blazing fast project scaffolding and resource generation.
@@ -102,7 +163,7 @@ 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:** `527`
+- **Total Tests:** `550`
 - **Status:** `All Passed`
 - **Framework:** [Vitest](https://vitest.dev/)
 - **Environment:** JSDOM (Browser simulation)
@@ -139,7 +200,7 @@ npx vitest
 ## Future Roadmap
 
 - [ ] Advanced state management and SSR support
-- [ ] Lightweight compiler which transforms declarative HTML into optimized runtime instructions
+- [x] Optimising the existing HTML compiler and remove useless DOM trasversals in lists
 - [ ] Integrated backend development support
 
 Built by me, Sebi Somu, a forward-thinking JavaScript Architect.

package/app/benchmark/vite.config.js

@@ -0,0 +1,23 @@
+import { defineConfig } from 'vite'
+import path from 'path'
+
+export default defineConfig({
+    root: './app/benchmark',
+
+    resolve: {
+        alias: {
+            'fusee-framework': path.resolve(__dirname, '../../framework'),
+        }
+    },
+
+    server: {
+        port: 5173,
+        open: true,
+        hmr: true,
+    },
+
+    build: {
+        outDir: '../../dist-benchmark',
+        emptyOutDir: true,
+    }
+})

package/auto-imports.d.ts

@@ -6,11 +6,14 @@
 // biome-ignore lint: disable
 export {}
 declare global {
+  const InjectionToken: typeof import('fusee-framework').InjectionToken
   const MutationType: typeof import('fusee-framework').MutationType
+  const assertSetupContext: typeof import('fusee-framework').assertSetupContext
   const batch: typeof import('fusee-framework').batch
   const clearStores: typeof import('fusee-framework').clearStores
   const computed: typeof import('fusee-framework').computed
   const defineComponent: typeof import('fusee-framework').defineComponent
+  const defineComposable: typeof import('fusee-framework').defineComposable
   const defineStore: typeof import('fusee-framework').defineStore
   const directive: typeof import('fusee-framework').directive
   const effect: typeof import('fusee-framework').effect
@@ -23,6 +26,7 @@ declare global {
   const onMount: typeof import('fusee-framework').onMount
   const onUnmount: typeof import('fusee-framework').onUnmount
   const provide: typeof import('fusee-framework').provide
+  const provideGlobal: typeof import('fusee-framework').provideGlobal
   const registerStorePlugin: typeof import('fusee-framework').registerStorePlugin
   const resetStore: typeof import('fusee-framework').resetStore
   const signal: typeof import('fusee-framework').signal

package/create-fusee-go/internal/assets/embed/framework/auto-import-preset.js

@@ -1,9 +1,15 @@
-export const FuseePreset = {
-    'fusee-framework': [
-        'signal', 'computed', 'effect', 'watch',
-        'batch', 'untrack', 'inspect', 'onCleanup',
-        'defineComponent', 'onMount', 'onUnmount',
-        'directive',
-        'mountOutlet', 'mountTemplate', 'emit'
-    ]
-}
+export const FuseePreset = {
+    'fusee-framework': [
+        'signal', 'computed', 'effect', 'watch',
+        'batch', 'untrack', 'inspect', 'onCleanup',
+        'defineComponent', 'onMount', 'onUnmount',
+        'directive',
+        'mountOutlet', 'mountTemplate', 'emit',
+        'defineStore', 'resetStore', 'clearStores',
+        'registerStorePlugin', 'useNestedStore',
+        'storeToRefs', 'storeToState', 'storeToGetters',
+        'MutationType',
+        'provide', 'inject', 'provideGlobal', 'InjectionToken',
+        'defineComposable', 'assertSetupContext'
+    ]
+}

package/create-fusee-go/internal/assets/embed/framework/core/async-context.js

@@ -0,0 +1,27 @@
+let _als = null
+
+export function _registerALS(als) {
+    _als = als
+}
+
+export function _getALS() {
+    return _als
+}
+
+export const _globalInFlightMaps = {
+    byKey: new Map(),
+    byFetcher: new WeakMap()
+}
+
+export function getInFlightStore() {
+    if (_als) {
+        const ctx = _als.getStore()
+        if (ctx) return ctx.inFlightMaps
+    }
+    return _globalInFlightMaps
+}
+
+export function isSSRContext() {
+    if (!_als) return false
+    return _als.getStore() !== undefined
+}

package/create-fusee-go/internal/assets/embed/framework/core/compiler/ast.js

@@ -0,0 +1,167 @@
+export const NodeType = {
+    ROOT: 'Root',
+    ELEMENT: 'Element',
+    COMPONENT: 'Component',
+    TEXT: 'Text',
+    INTERPOLATION: 'Interpolation',
+    EXPRESSION: 'Expression',
+    ATTRIBUTE: 'Attribute',
+    BINDING: 'Binding',
+    EVENT: 'Event',
+    DIRECTIVE: 'Directive',
+    SLOT_OUTLET: 'SlotOutlet',
+    SLOT_CONTENT: 'SlotContent'
+}
+
+export function createLoc(start, end, source) {
+    return { start, end, source }
+}
+
+export function createPos(line, col, offset) {
+    return { line, col, offset }
+}
+
+export function createRoot(children = [], loc = null) {
+    return { type: NodeType.ROOT, children, loc }
+}
+
+export function createElement(tag, props = [], children = [], selfClosing = false, loc = null) {
+    return {
+        type: NodeType.ELEMENT,
+        tag,
+        props,
+        children,
+        selfClosing,
+        isStatic: false,
+        hoisted: false,
+        loc
+    }
+}
+
+export function createComponent(name, props = [], slots = {}, loc = null) {
+    return {
+        type: NodeType.COMPONENT,
+        name,
+        props,
+        slots,
+        loc
+    }
+}
+
+export function createText(content, loc = null) {
+    return { type: NodeType.TEXT, content, loc }
+}
+
+export function createInterpolation(expression, loc = null) {
+    return {
+        type: NodeType.INTERPOLATION,
+        expression,
+        loc
+    }
+}
+
+export function createExpression(content, isStatic = false, loc = null) {
+    return {
+        type: NodeType.EXPRESSION,
+        content,
+        isStatic,
+        loc
+    }
+}
+
+export function createAttribute(name, value, loc = null) {
+    return {
+        type: NodeType.ATTRIBUTE,
+        name,
+        value,
+        loc
+    }
+}
+
+export function createBinding(name, expression, isProp = false, loc = null) {
+    return {
+        type: NodeType.BINDING,
+        name,
+        expression,
+        isProp,
+        loc
+    }
+}
+
+export function createEvent(name, expression, modifiers = [], loc = null) {
+    return {
+        type: NodeType.EVENT,
+        name,
+        expression,
+        modifiers,
+        loc
+    }
+}
+
+export function createDirective(name, expression = null, arg = null, loc = null) {
+    return {
+        type: NodeType.DIRECTIVE,
+        name,
+        expression,
+        arg,
+        loc
+    }
+}
+
+export function createSlotOutlet(slotName = 'default', fallback = [], loc = null) {
+    return {
+        type: NodeType.SLOT_OUTLET,
+        slotName,
+        fallback,
+        loc
+    }
+}
+
+export function createSlotContent(slotName = 'default', children = [], loc = null) {
+    return {
+        type: NodeType.SLOT_CONTENT,
+        slotName,
+        children,
+        loc
+    }
+}
+
+export function createForArg(item, source, index = null, loc = null) {
+    return { item, source, index, loc }
+}
+
+export function isElement(node) {
+    return node?.type === NodeType.ELEMENT
+}
+
+export function isComponent(node) {
+    return node?.type === NodeType.COMPONENT
+}
+
+export function isText(node) {
+    return node?.type === NodeType.TEXT
+}
+
+export function isInterpolation(node) {
+    return node?.type === NodeType.INTERPOLATION
+}
+
+export function isDirective(node, name) {
+    return node?.type === NodeType.DIRECTIVE && (name == null || node.name === name)
+}
+
+export function isStaticText(node) {
+    return node?.type === NodeType.TEXT || (node?.type === NodeType.INTERPOLATION && node.expression?.isStatic)
+}
+
+export function findDirective(element, name) {
+    return element.props.find(p => isDirective(p, name)) ?? null
+}
+
+export function getEvents(element) {
+    return element.props.filter(p => p.type === NodeType.EVENT)
+}
+
+export function cloneNode(node) {
+    return { ...node, props: node.props ? [...node.props] : undefined, children: node.children ? [...node.children] : undefined }
+}

package/create-fusee-go/internal/assets/embed/framework/core/compiler/errors-list.js

@@ -0,0 +1,47 @@
+export const ErrorCode = {
+    UNEXPECTED_CHAR: 'E001',
+    UNTERMINATED_STRING: 'E002',
+    UNTERMINATED_MUSTACHE: 'E003',
+    UNTERMINATED_TAG: 'E004',
+    MALFORMED_COMMENT: 'E005',
+    UNEXPECTED_TOKEN: 'P001',
+    MISSING_CLOSING_TAG: 'P002',
+    UNEXPECTED_CLOSING_TAG: 'P003',
+    INVALID_DIRECTIVE_SYNTAX: 'P004',
+    INVALID_FOR_SYNTAX: 'P005',
+    DUPLICATE_KEY: 'P006',
+    V_ELSE_NO_IF: 'P007',
+    EMPTY_EXPRESSION: 'P008',
+    INVALID_SLOT_NAME: 'P009',
+    DUPLICATE_DIRECTIVE: 'T001',
+    FOR_MISSING_KEY: 'T002',
+    MODEL_ON_NON_INPUT: 'T003',
+    COMPONENT_NOT_REGISTERED: 'T004',
+    UNKNOWN_IDENTIFIER: 'S001',
+    STATIC_FOR_KEY: 'S002',
+    UNKNOWN_NODE_TYPE: 'G001',
+}
+
+export const ERROR_MESSAGES = {
+    [ErrorCode.UNEXPECTED_CHAR]: 'Unexpected character "{0}"',
+    [ErrorCode.UNTERMINATED_STRING]: 'Unterminated string literal',
+    [ErrorCode.UNTERMINATED_MUSTACHE]: 'Unterminated mustache expression "{0}"',
+    [ErrorCode.UNTERMINATED_TAG]: 'Unterminated tag "<{0}"',
+    [ErrorCode.MALFORMED_COMMENT]: 'Malformed HTML comment',
+    [ErrorCode.UNEXPECTED_TOKEN]: 'Unexpected token "{0}", expected "{1}"',
+    [ErrorCode.MISSING_CLOSING_TAG]: 'Missing closing tag for <{0}>',
+    [ErrorCode.UNEXPECTED_CLOSING_TAG]: 'Unexpected closing tag </{0}>',
+    [ErrorCode.INVALID_DIRECTIVE_SYNTAX]: 'Invalid directive syntax: "{0}"',
+    [ErrorCode.INVALID_FOR_SYNTAX]: 'Invalid f-for syntax: "{0}". Expected "(item, index) in source" or "item in source"',
+    [ErrorCode.DUPLICATE_KEY]: 'Duplicate attribute "{0}" on element <{1}>',
+    [ErrorCode.V_ELSE_NO_IF]: 'f-else / f-else-if has no matching f-if',
+    [ErrorCode.EMPTY_EXPRESSION]: 'Expression in "{0}" must not be empty',
+    [ErrorCode.INVALID_SLOT_NAME]: 'Invalid slot name "{0}"',
+    [ErrorCode.DUPLICATE_DIRECTIVE]: 'Duplicate directive "f-{0}" on element <{1}>',
+    [ErrorCode.FOR_MISSING_KEY]: 'f-for on <{0}> is missing a :key binding — add :key="<unique expr>"',
+    [ErrorCode.MODEL_ON_NON_INPUT]: 'f-model can only be used on <input>, <textarea> or <select>, got <{0}>',
+    [ErrorCode.COMPONENT_NOT_REGISTERED]: 'Component "{0}" is used in the template but not registered',
+    [ErrorCode.UNKNOWN_NODE_TYPE]: 'Unknown AST node type "{0}" encountered in generator',
+    [ErrorCode.UNKNOWN_IDENTIFIER]: 'Unknown identifier "{0}" in expression "{1}" — not found in component scope',
+    [ErrorCode.STATIC_FOR_KEY]: ':key="{0}" is a static literal — keys must be unique per item (use a dynamic expression like :key="item.id")',
+}

package/create-fusee-go/internal/assets/embed/framework/core/compiler/errors.js

@@ -0,0 +1,107 @@
+import { ErrorCode, ERROR_MESSAGES } from './errors-list.js'
+
+export class CompileError extends Error {
+    constructor(code, loc, source, ...args) {
+        const template = ERROR_MESSAGES[code] ?? `Unknown compiler error (${code})`
+        const message  = _interpolate(template, args)
+        super(message)
+        this.name = 'CompileError'
+        this.code = code
+        this.loc = loc
+        this.source = source
+        this._snippet = null
+    }
+
+    format(filePath = '<template>') {
+        const { line, col } = this.loc?.start ?? { line: '?', col: '?' }
+        const header = `[fusée] ${this.name} ${this.code} at ${filePath}:${line}:${col}`
+        const snippet = this._buildSnippet()
+        return snippet ? `${header}\n${this.message}\n\n${snippet}` : `${header}\n${this.message}`
+    }
+
+    _buildSnippet() {
+        if (this._snippet !== null) return this._snippet
+        if (!this.source || !this.loc?.start) {
+            this._snippet = ''
+            return ''
+        }
+
+        const lines = this.source.split('\n')
+        const lineIdx = this.loc.start.line - 1
+        const col = this.loc.start.col
+        const CONTEXT = 2
+        const firstLine = Math.max(0, lineIdx - CONTEXT)
+        const lastLine = Math.min(lines.length - 1, lineIdx + CONTEXT)
+        const width = String(lastLine + 1).length
+        const parts = []
+
+        for (let i = firstLine; i <= lastLine; i++) {
+            const lineNo = String(i + 1).padStart(width, ' ')
+            const prefix = i === lineIdx ? '> ' : '  '
+            parts.push(`${prefix}${lineNo} | ${lines[i]}`)
+            if (i === lineIdx) {
+                const caretPad = ' '.repeat(width + 4 + (col - 1))
+                const caretLen = Math.max(1, (this.loc.end?.col ?? col) - col)
+                parts.push(`${caretPad}${'~'.repeat(caretLen)}`)
+            }
+        }
+
+        this._snippet = parts.join('\n')
+        return this._snippet
+    }
+}
+
+export class CompileWarning {
+    constructor(code, loc, source, ...args) {
+        const template = ERROR_MESSAGES[code] ?? `Unknown compiler warning (${code})`
+        this.message = _interpolate(template, args)
+        this.code = code
+        this.loc = loc
+        this.source = source
+    }
+
+    format(filePath = '<template>') {
+        const { line, col } = this.loc?.start ?? { line: '?', col: '?' }
+        return `[fusée] Warning ${this.code} at ${filePath}:${line}:${col}\n${this.message}`
+    }
+}
+
+export class ErrorCollector {
+    constructor(source) {
+        this.source = source
+        this.errors = []
+        this.warnings = []
+    }
+
+    error(code, loc, ...args) {
+        const err = new CompileError(code, loc, this.source, ...args)
+        this.errors.push(err)
+        return err
+    }
+
+    warn(code, loc, ...args) {
+        const w = new CompileWarning(code, loc, this.source, ...args)
+        this.warnings.push(w)
+        return w
+    }
+
+    throwIfAny() {
+        if (this.errors.length > 0) throw this.errors[0]
+    }
+
+    get hasErrors() {
+        return this.errors.length > 0
+    }
+
+    get hasWarnings() {
+        return this.warnings.length > 0
+    }
+}
+
+function _interpolate(template, args) {
+    return template.replace(/\{(\d+)\}/g, (_, i) => args[i] ?? '')
+}
+
+export function throwError(code, loc, source, ...args) {
+    throw new CompileError(code, loc, source, ...args)
+}