fusee-framework 1.8.0 → 1.9.1

package/framework/core/compiler/plugins/actions-plugin.js

@@ -0,0 +1,263 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const ACTION_BASE_URL = '/__fusee/actions'
+const VIRTUAL_CLIENT_ID = 'virtual:fusee-actions'
+const VIRTUAL_SERVER_ID = 'virtual:fusee-action-routes'
+
+export function actionsPlugin(options = {}) {
+    const {
+        serverActionsFile = 'src/actions.server.js',
+        clientActionsFile = 'src/actions.js',
+        baseUrl = ACTION_BASE_URL,
+        typesOutput = 'src/types/actions.d.ts',
+    } = options
+
+    let resolvedServerFile = null
+    let resolvedClientFile = null
+
+    return {
+        name: 'vite-plugin-fusee-actions',
+
+        configResolved(config) {
+            resolvedServerFile = path.resolve(config.root, serverActionsFile)
+            resolvedClientFile = path.resolve(config.root, clientActionsFile)
+        },
+
+        resolveId(id) {
+            if (id === VIRTUAL_CLIENT_ID)
+                return '\0' + VIRTUAL_CLIENT_ID
+            if (id === VIRTUAL_SERVER_ID)
+                return '\0' + VIRTUAL_SERVER_ID
+        },
+
+        async load(id) {
+            if (id === '\0' + VIRTUAL_CLIENT_ID) {
+                const serverActions = _extractServerActions(resolvedServerFile)
+                const clientActions = resolvedClientFile ? _extractClientActions(resolvedClientFile) : []
+
+                const { warnings, errors } = validateActions(serverActions, clientActions)
+                for (const w of warnings)
+                    this.warn(w)
+                for (const e of errors)
+                    this.error(e)
+
+                return generateClientStubs(serverActions, { baseUrl })
+            }
+
+            if (id === '\0' + VIRTUAL_SERVER_ID) {
+                const serverActions = _extractServerActions(resolvedServerFile)
+                return generateServerRoutes(serverActions, { serverActionsFile, baseUrl })
+            }
+        },
+
+        async buildEnd() {
+            if (typesOutput && resolvedServerFile) {
+                const serverActions = _extractServerActions(resolvedServerFile)
+                const types = generateActionTypes(serverActions)
+                const absOutput = path.resolve(process.cwd(), typesOutput)
+                fs.mkdirSync(path.dirname(absOutput), { recursive: true })
+                fs.writeFileSync(absOutput, types, 'utf8')
+            }
+        },
+
+        handleHotUpdate({ file, server }) {
+            if (file === resolvedServerFile || file === resolvedClientFile) {
+                const mod = server.moduleGraph.getModuleById('\0' + VIRTUAL_CLIENT_ID)
+                if (mod) 
+                    server.moduleGraph.invalidateModule(mod)
+                server.ws.send({ type: 'full-reload' })
+            }
+        },
+    }
+}
+
+export function _extractServerActions(filePath) {
+    if (!filePath || !fs.existsSync(filePath)) 
+        return []
+
+    const source = fs.readFileSync(filePath, 'utf8')
+    const actions = []
+
+    const RE_EXPORT = /export\s+(?:const|let|var)\s+(\w+)\s*=\s*defineAction\s*\(/g
+    const RE_NAMED = /defineAction\s*\(\s*(?:async\s+)?function\s+(\w+)/g
+    const RE_OPTS = /defineAction\s*\([^,)]+,\s*\{[^}]*name\s*:\s*['"](\w+)['"]/g
+
+    const seen = new Set()
+
+    let m
+    while ((m = RE_EXPORT.exec(source)) !== null) {
+        const name = m[1]
+        if (!seen.has(name)) { seen.add(name); actions.push({ name, exportName: name }) }
+    }
+
+    while ((m = RE_NAMED.exec(source)) !== null) {
+        const name = m[1]
+        if (!seen.has(name)) { seen.add(name); actions.push({ name, exportName: name }) }
+    }
+
+    while ((m = RE_OPTS.exec(source)) !== null) {
+        const name = m[1]
+        if (!seen.has(name)) { seen.add(name); actions.push({ name, exportName: name }) }
+    }
+
+    return actions
+}
+
+export function _extractClientActions(filePath) {
+    if (!filePath || !fs.existsSync(filePath)) 
+        return []
+
+    const source = fs.readFileSync(filePath, 'utf8')
+    const names = []
+    const RE = /defineAction\s*\(\s*['"](\w+)['"]/g
+    let m
+
+    while ((m = RE.exec(source)) !== null) {
+        names.push(m[1])
+    }
+
+    return names
+}
+
+export function validateActions(serverActions, clientActions) {
+    const warnings = []
+    const errors = []
+
+    const serverNames = new Set(serverActions.map(a => a.name))
+    const clientNames = new Set(clientActions)
+
+    for (const name of clientNames) {
+        if (!serverNames.has(name)) {
+            errors.push(`[fusée] Action "${name}" is defined on the client but has no corresponding defineAction() in actions.server.js`)
+        }
+    }
+
+    for (const name of serverNames) {
+        if (!clientNames.has(name) && clientActions.length > 0) {
+            warnings.push(`[fusée] Action "${name}" is defined on the server but is not used in actions.js — it will still be accessible via HTTP POST /${name}`
+            )
+        }
+    }
+
+    return { warnings, errors }
+}
+
+export function generateClientStubs(actions, options = {}) {
+    const { baseUrl = ACTION_BASE_URL } = options
+
+    const lines = [
+        '// [fusée] Auto-generated action stubs — do not edit',
+        '// Generated by compiler/plugins/actions-plugin.js',
+        '',
+        `import { createActionProxy, useAction } from '../core/actions.js'`,
+        '',
+    ]
+
+    for (const action of actions) {
+        lines.push(`export const ${action.exportName} = createActionProxy(` +    `${JSON.stringify(action.name)}, { baseUrl: ${JSON.stringify(baseUrl)} })`)
+    }
+
+    lines.push('')
+    lines.push('export { useAction }')
+    lines.push('')
+
+    return lines.join('\n')
+}
+
+export function generateServerRoutes(actions, options = {}) {
+    const {
+        serverActionsFile = 'src/actions.server.js',
+        baseUrl = ACTION_BASE_URL,
+    } = options
+
+    const relPath = './' + serverActionsFile.replace(/^src\//, '')
+
+    const lines = [
+        '// [fusée] Auto-generated action routes — do not edit',
+        '// Generated by compiler/plugins/actions-plugin.js',
+        '',
+        `import { handleActionRequest, getRegisteredActions } from ${JSON.stringify(relPath)}`,
+        '',
+        '// Import side-effect: registers all actions in the registry',
+        `import ${JSON.stringify(relPath)}`,
+        '',
+        '/** Map of action name → request handler */',
+        'export const actionHandlers = {',
+    ]
+
+    for (const action of actions) {
+        lines.push(`  ${JSON.stringify(action.name)}: (req, res) => handleActionRequest(req, res),`)
+    }
+
+    lines.push('}')
+    lines.push('')
+    lines.push('/**')
+    lines.push(' * Mount all action routes on an Express app.')
+    lines.push(' * @param {import("express").Application} app')
+    lines.push(' */')
+    lines.push('export function mountActionRoutes(app) {')
+    lines.push(`  const base = ${JSON.stringify(baseUrl)}`)
+    lines.push('  for (const [name, handler] of Object.entries(actionHandlers)) {')
+    lines.push('    app.post(`${base}/${name}`, handler)')
+    lines.push('  }')
+    lines.push('}')
+    lines.push('')
+    lines.push('/**')
+    lines.push(' * Fetch API compatible dispatcher (Bun / Deno / CF Workers).')
+    lines.push(' * @param {Request} request')
+    lines.push(' */')
+    lines.push('export async function dispatchAction(request) {')
+    lines.push(`  const base = ${JSON.stringify(baseUrl)}`)
+    lines.push('  const url  = new URL(request.url)')
+    lines.push('  const name = url.pathname.slice(base.length + 1)')
+    lines.push('  const handler = actionHandlers[name]')
+    lines.push('  if (!handler) return new Response(JSON.stringify({ error: `Action "${name}" not found` }), { status: 404 })')
+    lines.push('  return handler(request, null)')
+    lines.push('}')
+    lines.push('')
+
+    return lines.join('\n')
+}
+
+export function generateActionTypes(actions) {
+    const lines = [
+        '// [fusée] Auto-generated action types — do not edit',
+        '// Generated by compiler/plugins/actions-plugin.js',
+        '',
+        "import type { useAction } from '../core/actions.js'",
+        '',
+        '/** All registered server action names */',
+        `export type ActionName = ${actions.map(a => JSON.stringify(a.name)).join(' | ') || 'never'}`,
+        '',
+        '/** Client proxy function for a server action */',
+        'export type ActionProxy<TArgs extends unknown[] = unknown[], TReturn = unknown> =',
+        '  ((...args: TArgs) => Promise<TReturn>) & {',
+        '    _isAction: true',
+        '    _actionName: string',
+        '  }',
+        '',
+        '/** useAction() result shape */',
+        'export type UseActionResult<TReturn = unknown> = {',
+        '  execute: (...args: unknown[]) => Promise<TReturn | undefined>',
+        '  pending: () => boolean',
+        '  data: () => TReturn | undefined',
+        '  error: () => Error | undefined',
+        '  reset: () => void',
+        '}',
+        '',
+        '/** Auto-generated action stubs */',
+        'export declare const actionStubs: Record<ActionName, ActionProxy>',
+        '',
+    ]
+
+    for (const action of actions) {
+        lines.push(`export declare const ${action.exportName}: ActionProxy`)
+    }
+
+    lines.push('')
+    lines.push("export { useAction } from '../core/actions.js'")
+    lines.push('')
+
+    return lines.join('\n')
+}

package/framework/core/compiler/plugins/compiler-plugin.d.ts

@@ -0,0 +1,5 @@
+export declare function fuseeCompilerPlugin(): {
+    name: 'vite-plugin-fusee-compiler'
+    enforce: 'pre'
+    transform(code: string, id: string): { code: string; map: null } | null
+}

package/framework/core/compiler/plugins/compiler-plugin.js

@@ -0,0 +1,45 @@
+import { compile } from '../main-compiler.js';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const IMPORT_RE = /^import\s+(?:\{[^}]*\}|[\w$]+)\s+from\s+['"]([^'"]+\.template\.html)['"]\s*;?/gm;
+
+export function fuseeCompilerPlugin() {
+    return {
+        name: 'vite-plugin-fusee-compiler',
+        enforce: 'pre',
+
+        transform(code, id) {
+            if (!id.endsWith('.js') && !id.endsWith('.ts')) 
+                return null;
+            if (!IMPORT_RE.test(code)) 
+                return null;
+
+            IMPORT_RE.lastIndex = 0;
+
+            let result = code;
+            let match;
+
+            while ((match = IMPORT_RE.exec(code)) !== null) {
+                const [fullImport, templatePath] = match;
+                const absPath = path.resolve(path.dirname(id), templatePath);
+                const source = fs.readFileSync(absPath, 'utf-8');
+                const { code: compiledCode } = compile(source, {
+                    runtimePath: 'fusee-framework/core/h.js'
+                });
+
+                const namedMatch = fullImport.match(/\{\s*render\s+as\s+([\w$]+)\s*\}/);
+                const defaultMatch = fullImport.match(/import\s+([\w$]+)\s+from/);
+                const localName = namedMatch ? namedMatch[1] : (defaultMatch ? defaultMatch[1] : 'render');
+                const inlined = compiledCode.replace(
+                    'export function render(',
+                    `function ${localName}(`
+                );
+
+                result = result.replace(fullImport, inlined);
+            }
+
+            return { code: result, map: null };
+        }
+    };
+}

package/framework/core/compiler/plugins/file-router-plugin.js

@@ -0,0 +1,301 @@
+import path from 'node:path'
+
+export function fileRouterPlugin(options = {}) {
+    const {
+        pagesDir = 'src/pages',
+        loadingComponent = null,
+    } = options
+
+    return {
+        name: 'vite-plugin-fusee-file-router',
+        async buildStart() { },
+
+        resolveId(id) {
+            if (id === 'virtual:fusee-routes') return '\0virtual:fusee-routes'
+        },
+
+        async load(id) {
+            if (id !== '\0virtual:fusee-routes') return null
+
+            const { globSync } = await import('fast-glob')
+            const files = globSync(`${pagesDir}/**/*.{js,ts,jsx,tsx}`, {
+                cwd: process.cwd(),
+                absolute: false,
+            })
+
+            const routes = compileFileRoutes(files, { pagesDir, loadingComponent })
+            return generateRoutesModule(routes, pagesDir)
+        },
+    }
+}
+
+export function compileFileRoutes(files, options = {}) {
+    const { pagesDir = 'src/pages' } = options
+
+    const entries = _parseFileEntries(files, pagesDir)
+    const tree = _buildRouteTree(entries, false)
+    _sortRoutesRecursive(tree)
+
+    return tree
+}
+
+export function generateRoutesModule(routes, pagesDir = 'src/pages') {
+    const imports = []
+    const lines = []
+
+    _collectImports(routes, pagesDir, imports)
+
+    lines.push('// [fusée] Auto-generated at build-time — do not edit')
+    lines.push('// Generated by compiler/plugins/file-router-plugin.js')
+    lines.push('')
+
+    for (const { varName, filePath } of imports) {
+        lines.push(`const ${varName} = () => import(${JSON.stringify(filePath)})`)
+    }
+
+    lines.push('')
+    lines.push(`export const routes = ${_serializeRoutes(routes)}`)
+    lines.push('')
+    lines.push('export default routes')
+
+    return lines.join('\n')
+}
+
+export function validateRoutes(routes) {
+    const warnings = []
+    const errors = []
+
+    _validateLevel(routes, '', warnings, errors)
+
+    return { warnings, errors }
+}
+
+function _validateLevel(routes, prefix, warnings, errors) {
+    const seenPaths = new Map()
+    const paramNames = new Set()
+
+    for (const route of routes) {
+        const fullPath = prefix + route.path
+        if (seenPaths.has(route.path)) {
+            errors.push(`Duplicate route path "${fullPath}" — defined in multiple page files`)
+        } else {
+            seenPaths.set(route.path, route)
+        }
+        const paramMatch = route.path.match(/^:([^/]+)/)
+        if (paramMatch) {
+            const paramName = paramMatch[1]
+            if (paramNames.size > 0 && !paramNames.has(paramName)) {
+                warnings.push(`Conflicting dynamic segments at "${prefix}*": found ":${[...paramNames][0]}" and ":${paramName}" — only one dynamic segment per level is allowed`)
+            }
+            paramNames.add(paramName)
+        }
+        if (route.children !== undefined && route.children.length === 0) {
+            warnings.push(`Layout route "${fullPath}" has no children — it will never render any content`)
+        }
+
+        if (route.children) {
+            _validateLevel(route.children, fullPath + '/', warnings, errors)
+        }
+    }
+}
+
+export function generateRouteTypes(routes) {
+    const paths = []
+    const paramTypes = []
+
+    _collectRoutePaths(routes, '', paths, paramTypes)
+
+    const pathUnion = paths.map(p => JSON.stringify(p)).join('\n  | ')
+    const paramEntries = paramTypes
+        .filter(e => Object.keys(e.params).length > 0)
+        .map(e => {
+            const paramFields = Object.entries(e.params)
+                .map(([k, v]) => `${k}: ${v}`)
+                .join('; ')
+            return `  ${JSON.stringify(e.path)}: { ${paramFields} }`
+        })
+        .join('\n')
+
+    return [
+        '// [fusée] Auto-generated route types — do not edit',
+        '// Generated by compiler/plugins/file-router-plugin.js',
+        '',
+        '/** All valid application route paths */',
+        `export type AppRoute =`,
+        `  | ${pathUnion}`,
+        '',
+        '/** Route params per path (only paths with dynamic segments) */',
+        'export type RouteParams = {',
+        paramEntries,
+        '}',
+        '',
+        '/** Extract params for a specific route */',
+        'export type ParamsFor<T extends AppRoute> =',
+        '  T extends keyof RouteParams ? RouteParams[T] : Record<string, never>',
+        '',
+    ].join('\n')
+}
+
+function _parseFileEntries(files, pagesDir) {
+    return files.map(filePath => {
+        let cleanPath = filePath
+            .replace(new RegExp(`^${pagesDir}/?`), '')
+            .replace(/\.[jt]sx?$/, '')
+
+        const parts = cleanPath.split('/')
+        const rawFileName = parts.pop()
+        const rawDirSegs = parts
+        const dirSegments = rawDirSegs.map(_transformSegment)
+        const fileName = _transformSegment(rawFileName)
+        const isIndex = rawFileName === 'index'
+        const isCatchAll = /^\.\.\./.test(rawFileName)
+
+        return { filePath, dirSegments, fileName, isIndex, isCatchAll }
+    })
+}
+
+function _transformSegment(seg) {
+    return seg
+        .replace(/\[\.\.\.([^\]]+)\]/g, '*')
+        .replace(/\[([^\]]+)\]/g, ':$1')
+}
+
+function _buildRouteTree(entries, isChild) {
+    const filesHere = new Map()
+    const grouped   = new Map()
+
+    for (const entry of entries) {
+        if (entry.dirSegments.length === 0) {
+            filesHere.set(entry.fileName, entry)
+        } else {
+            const firstDir = entry.dirSegments[0]
+            if (!grouped.has(firstDir)) grouped.set(firstDir, [])
+            grouped.get(firstDir).push(entry)
+        }
+    }
+
+    let rootLayoutEntry = null
+    if (filesHere.has('_layout')) {
+        rootLayoutEntry = filesHere.get('_layout')
+        filesHere.delete('_layout')
+    }
+
+    const routes      = []
+    const usedAsLayout = new Set()
+
+    for (const [dirName, dirEntries] of grouped) {
+        const layoutEntry = filesHere.get(dirName)
+
+        if (layoutEntry) {
+            usedAsLayout.add(dirName)
+            const childEntries = dirEntries.map(e => ({
+                ...e,
+                dirSegments: e.dirSegments.slice(1)
+            }))
+            const children = _buildRouteTree(childEntries, true)
+            routes.push({
+                path:      isChild ? dirName : '/' + dirName,
+                filePath:  layoutEntry.filePath,
+                children,
+            })
+        } else {
+            for (const entry of dirEntries) {
+                const segments = [...entry.dirSegments]
+                if (!entry.isIndex) segments.push(entry.fileName)
+                routes.push({
+                    path:     isChild ? segments.join('/') : '/' + segments.join('/'),
+                    filePath: entry.filePath,
+                })
+            }
+        }
+    }
+
+    for (const [name, entry] of filesHere) {
+        if (usedAsLayout.has(name)) continue
+        if (entry.isIndex) {
+            routes.push({ path: isChild ? '' : '/', filePath: entry.filePath })
+        } else if (entry.isCatchAll || name === '*') {
+            routes.push({ path: '*', filePath: entry.filePath })
+        } else {
+            routes.push({ path: isChild ? name : '/' + name, filePath: entry.filePath })
+        }
+    }
+
+    if (rootLayoutEntry) {
+        return [{ path: '', filePath: rootLayoutEntry.filePath, children: routes }]
+    }
+
+    return routes
+}
+
+function _sortRoutesRecursive(routes) {
+    routes.sort(_compareRoutes)
+    for (const route of routes) {
+        if (route.children) _sortRoutesRecursive(route.children)
+    }
+}
+
+function _compareRoutes(a, b) {
+    if (a.path === '*' && b.path !== '*') return 1
+    if (a.path !== '*' && b.path === '*') return -1
+    const aWild = a.path.endsWith('/*')
+    const bWild = b.path.endsWith('/*')
+    if (aWild && !bWild) return 1
+    if (!aWild && bWild) return -1
+    const aDyn = a.path.includes(':')
+    const bDyn = b.path.includes(':')
+    if (aDyn && !bDyn) return 1
+    if (!aDyn && bDyn) return -1
+    if (a.children && !b.children) return -1
+    if (!a.children && b.children) return 1
+    return a.path.localeCompare(b.path)
+}
+
+let _importCounter = 0
+
+function _collectImports(routes, pagesDir, imports) {
+    for (const route of routes) {
+        if (route.filePath) {
+            const varName = `_page${_importCounter++}`
+            route._varName = varName
+            imports.push({ varName, filePath: './' + route.filePath })
+        }
+        if (route.children) 
+            _collectImports(route.children, pagesDir, imports)
+    }
+}
+
+function _serializeRoutes(routes) {
+    const items = routes.map(route => {
+        const parts = [`path: ${JSON.stringify(route.path)}`]
+        if (route._varName) {
+            parts.push(`component: ${route._varName}`)
+        }
+        if (route.children) {
+            parts.push(`children: ${_serializeRoutes(route.children)}`)
+        }
+        return `{ ${parts.join(', ')} }`
+    })
+    return `[\n  ${items.join(',\n  ')}\n]`
+}
+
+function _collectRoutePaths(routes, prefix, paths, paramTypes) {
+    for (const route of routes) {
+        const fullPath = prefix + route.path
+        if (fullPath) {
+            paths.push(fullPath)
+
+            const params = {}
+            const paramRe = /:([^/]+)/g
+            let m
+            while ((m = paramRe.exec(fullPath)) !== null) {
+                params[m[1]] = 'string'
+            }
+            paramTypes.push({ path: fullPath, params })
+        }
+
+        if (route.children) {
+            _collectRoutePaths(route.children, fullPath + '/', paths, paramTypes)
+        }
+    }
+}