fusee-framework 1.8.0 → 1.9.1

package/framework/types/compiler/main-compiler.d.ts

@@ -0,0 +1,60 @@
+import type { RootNode } from './ast.js'
+import type { Token } from './lexer.js'
+import type { CompileWarning } from './errors.js'
+import type { CompileError } from './errors.js'
+
+export interface CompileOptions {
+    components?: string[] | Set<string>
+    runtimePath?: string
+    filename?: string
+    throwOnWarning?: boolean
+    scope?: string[]
+}
+
+export interface CompileResult {
+    code: string
+    ast: RootNode
+    tokens: Token[]
+    warnings: CompileWarning[]
+}
+
+export interface ParseOnlyResult {
+    ast: RootNode
+    tokens: Token[]
+}
+
+export interface BatchEntry {
+    id: string
+    source: string
+}
+
+export interface BatchResult {
+    id: string
+    code: string | null
+    warnings: CompileWarning[]
+    error: CompileError | null
+}
+
+export declare function compile(source: string, options?: CompileOptions): CompileResult
+export declare function parseOnly(source: string, options?: Pick<CompileOptions, 'components'>): ParseOnlyResult
+export declare function transformOnly(ast: RootNode, options?: Pick<CompileOptions, 'components' | 'scope'> & { source?: string }): { ast: RootNode; warnings: CompileWarning[] }
+export declare function compileBatch(templates: BatchEntry[], sharedOptions?: CompileOptions): BatchResult[]
+
+export interface FuseePluginOptions {
+    runtimePath?: string
+    components?: string[]
+    scope?: string[]
+}
+
+export declare function fuseePlugin(options?: FuseePluginOptions): {
+    name: 'vite-plugin-fusee'
+    transform(src: string, id: string): { code: string; map: null } | null
+}
+
+export { fileRouterPlugin } from './plugins/file-router-plugin.js'
+export { actionsPlugin } from './plugins/actions-plugin.js'
+export { routerPlugin } from './plugins/router-plugin.js'
+export { fuseeCompilerPlugin } from './plugins/compiler-plugin.js'
+export { compileFileRoutes, generateRoutesModule, generateRouteTypes, validateRoutes as validateFileRoutes } from './plugins/file-router-plugin.js'
+export { validateActions, generateClientStubs, generateServerRoutes, generateActionTypes } from './plugins/actions-plugin.js'
+export { validateRoutes, generateRouterTypes } from './plugins/router-plugin.js'

package/framework/types/compiler/parser.d.ts

@@ -0,0 +1,4 @@
+import type { Token } from './lexer.js'
+import type { RootNode } from './ast.js'
+
+export declare function parse(tokens: Token[], source: string, components?: Set<string>): RootNode

package/framework/types/compiler/plugins/actions.d.ts

@@ -0,0 +1,30 @@
+export interface ActionsPluginOptions {
+    serverActionsFile?: string
+    clientActionsFile?: string
+    baseUrl?: string
+    typesOutput?: string
+}
+
+export interface ActionDef {
+    name: string
+    exportName: string
+}
+
+export interface ActionValidationResult {
+    warnings: string[]
+    errors: string[]
+}
+
+export declare function actionsPlugin(options?: ActionsPluginOptions): {
+    name: 'vite-plugin-fusee-actions'
+    configResolved(config: { root: string }): void
+    resolveId(id: string): string | undefined
+    load(id: string): Promise<string | null>
+    buildEnd(): Promise<void>
+    handleHotUpdate(ctx: { file: string; server: unknown }): void
+}
+
+export declare function validateActions(serverActions: ActionDef[], clientActions: string[]): ActionValidationResult
+export declare function generateClientStubs(actions: ActionDef[], options?: { baseUrl?: string }): string
+export declare function generateServerRoutes(actions: ActionDef[], options?: { serverActionsFile?: string; baseUrl?: string }): string
+export declare function generateActionTypes(actions: ActionDef[]): string

package/framework/types/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/types/compiler/plugins/file-router-plugins.d.ts

@@ -0,0 +1,32 @@
+export interface FileRouterPluginOptions {
+    pagesDir?: string
+    loadingComponent?: unknown
+}
+
+export interface RouteNode {
+    path: string
+    filePath?: string
+    children?: RouteNode[]
+}
+
+export interface RouteValidationResult {
+    warnings: string[]
+    errors: string[]
+}
+
+export interface ImportEntry {
+    varName: string
+    filePath: string
+}
+
+export declare function fileRouterPlugin(options?: FileRouterPluginOptions): {
+    name: 'vite-plugin-fusee-file-router'
+    buildStart(): Promise<void>
+    resolveId(id: string): string | undefined
+    load(id: string): Promise<string | null>
+}
+
+export declare function compileFileRoutes(files: string[], options?: { pagesDir?: string }): RouteNode[]
+export declare function generateRoutesModule(routes: RouteNode[], pagesDir?: string): string
+export declare function validateRoutes(routes: RouteNode[]): RouteValidationResult
+export declare function generateRouteTypes(routes: RouteNode[]): string

package/framework/types/compiler/plugins/router-plugin.d.ts

@@ -0,0 +1,24 @@
+export interface RouterPluginOptions {
+    typesOutput?: string
+    pagesDir?: string
+    strict?: boolean
+}
+
+export interface RouteNode {
+    path: string
+    filePath?: string
+    children?: RouteNode[]
+}
+
+export interface RouteValidationResult {
+    warnings: string[]
+    errors: string[]
+}
+
+export declare function routerPlugin(options?: RouterPluginOptions): {
+    name: 'vite-plugin-fusee-router'
+    generateBundle(): Promise<void>
+}
+
+export declare function validateRoutes(routes: RouteNode[]): RouteValidationResult
+export declare function generateRouterTypes(routes: RouteNode[]): string

package/framework/types/compiler/transformer.d.ts

@@ -0,0 +1,28 @@
+import type { RootNode }       from './ast.js'
+import type { CompileWarning } from './errors.js'
+
+export interface TransformOptions {
+    components?: Set<string>
+    source?: string
+    scope?: string[]
+}
+
+export interface TransformResult {
+    ast: RootNode
+    warnings: CompileWarning[]
+}
+
+/**
+ * Run all transformer steps on the Root AST (mutates in-place).
+ *
+ * Steps:
+ *  1. markStatic — bottom-up static marking
+ *  2. hoistStatic — collect f-once + multi-static-child subtrees
+ *  3. chainConditionals — f-if / f-else-if / f-else -> IfNode
+ *  4. validateFor — warn on f-for without :key  (T002)
+ *  5. validateModel — warn on f-model on non-input  (T003)
+ *  6. validateComponents — warn on unregistered component  (T004)
+ *  7. analyseScope — resolve identifiers (needs `scope`)
+ *  8. validateExpressions — warn on unknown identifiers (S001) + static :key (S002)
+ */
+export declare function transform(ast: RootNode, options?: TransformOptions): TransformResult

package/framework/types/hydration.d.ts

@@ -0,0 +1,30 @@
+export interface HydrationCacheEntry {
+    data: unknown
+    updatedAt: number
+}
+
+export type HydrationSnapshot = Record<string, Record<string, HydrationCacheEntry>>
+export declare function _registerResourceCache(
+    resourceKey: string,
+    cache: Map<string, HydrationCacheEntry>
+): void
+
+export declare function extractHydrationData(): HydrationSnapshot
+export declare function dehydrate(snapshot?: HydrationSnapshot): string
+export declare function loadHydration(snapshot: HydrationSnapshot): void
+export declare function hydrateFromWindow(): void
+export declare function getHydratedEntries(resourceKey: string): Map<string, HydrationCacheEntry> | null
+export declare function isHydrationFresh(
+    resourceKey: string,
+    cacheKey: string,
+    staleTime?: number
+): boolean
+
+export declare function clearHydration(): void
+export declare function getHydrationSnapshot(): HydrationSnapshot
+
+declare global {
+    interface Window {
+        __FUSEE_HYDRATION__?: HydrationSnapshot
+    }
+}

package/framework/types/index.d.ts

@@ -8,6 +8,8 @@ export * from './store'
 export * from './event-delegation'
 export * from './di'
 export * from './reconcile'
+export * from './actions'
+export * from './actions.server'
 
 declare global {
     type Signal<T = any> = import('./signal').Signal<T>
@@ -30,3 +32,7 @@ declare global {
 }
 
 export as namespace Fusee
+
+declare module '*.template.html' {
+    export const render: (_ctx: any, _components: any) => any[]
+}

package/framework/types/server.d.ts

@@ -0,0 +1,11 @@
+export interface RequestContext {
+    inFlightMaps: {
+        byKey: Map<string, Promise<any>>
+        byFetcher: WeakMap<Function, Map<string, Promise<any>>>
+    }
+}
+
+export declare function createRequestContext(): RequestContext
+export declare function withRequestContext<T>(ctx: RequestContext, fn: () => T): T
+export declare function getInFlightStore(): RequestContext['inFlightMaps']
+export declare function isSSRContext(): boolean

package/framework/types/signal.d.ts

@@ -60,11 +60,6 @@ export interface WatchOptions {
     equals?: (a: any, b: any) => boolean;
 }
 
-export interface ResourceOptions {
-    staleTime?: number;
-    key?: string | number;
-}
-
 export type ResourceAccessor<T> = {
     (): T | undefined;
     read(): T;
@@ -116,13 +111,13 @@ export declare function onCleanup(fn: () => void): void
 
 export function resource<T, R = any>(
     fetcher: (input: R) => Promise<T>,
-    options?: { key?: string | number; staleTime?: number }
+    options?: ResourceOptions
 ): ResourceReturn<T, R>;
 
 export function resource<T, R>(
     source: () => R,
     fetcher: (input: R) => Promise<T>,
-    options?: { key?: string | number; staleTime?: number }
+    options?: ResourceOptions
 ): ResourceReturn<T, R>;
 
 export function createSuspense<T>(

package/ghid_go_fusee_integrat_go1_26.txt

@@ -0,0 +1,276 @@
+Ghid integrat: Construirea serverului Fusee în Go 1.26 — ghid tehnic detaliat și bune practici
+
+Scopul acestui fișier
+- Un ghid tehnic complet, în limba română, pentru construirea serverului Fusee în Go (versiunea 1.26). Integrează cele două ghiduri anterioare: un ghid general pentru server Fusee în Go și un ghid tehnic actualizat specific Go 1.26.
+- Public țintă: student CS care dezvoltă Fusee (framework JS cu reactivitate fină) și are nevoie de un backend scalabil în Go pentru orchestrare compilare, servire artefacte, build pipeline, caching, multi-tenant, observabilitate și securitate.
+
+Sumar rapid
+1. Motivație pentru Go
+2. Ce e nou în Go 1.26 și implicații practice
+3. Reguli explicite pentru editorul AI / echipă
+4. Setup și toolchain (Go 1.26)
+5. Arhitectură recomandată proiect
+6. Concurență în Go: modele, pattern-uri și scenarii Fusee
+7. Implementări concrete: worker pool, errgroup, rate limiting, backpressure
+8. HTTP server design și API pentru Fusee
+9. Job orchestration: sync vs async, cache, deduplicare, multi-tenant
+10. Securitate, izolare runner, sandboxing
+11. Observabilitate, tracing și profilare (incl. goroutine leak profile 1.26)
+12. Testing: unit, integration, golden, differential, leak tests
+13. CI/CD, Dockerfile, producție
+14. Performanță și optimizări practice
+15. Anti-patterns și greșeli comune
+16. Checklist de migrare JS → Go
+17. Plan de învățare și implementare 90+ zile
+18. Resurse și linkuri utile
+
+1) De ce Go pentru serverul Fusee
+- Simplitate, viteza de dezvoltare și ecosistem pentru servere networked.
+- Model de concurență ușor de folosit (goroutines + channels) ideal pentru orchestration.
+- Toolchain stabil, cross-compilation simplă, suport bun pentru containerizare și cloud native.
+- Go 1.26 aduce optimizări GC și instrumente utile (goroutine leak profile) care ajută la construirea unui server robust.
+
+2) Ce e nou în Go 1.26 (rezumat relevant)
+- Green Tea garbage collector activ implicit (reduce overhead GC pentru alocări mici și concu- intensive).
+- `errors.AsType[E error](err)` — verificări tip-sigure pentru erori.
+- `new(expr)` — permite `new` cu expresii (utile pentru pointere inițializate inline în DTO-uri).
+- Experimental: `simd/archsimd`, `runtime/secret`, `goroutineleak` profile.
+- `go fix` modernizat — automatizări pentru modernizarea codului.
+Referințe oficiale: https://go.dev/doc/go1.26 și https://go.dev/blog/go1.26
+
+3) Reguli explicite pentru editorul AI / echipă
+- Propagă `context.Context` în toate apelurile I/O, job-run și comunicare între componente.
+- Nu lansa goroutine fără mecanism de oprire: folosește `context`, `WaitGroup`, canale, `errgroup`.
+- Nu inventa API extern: folosește API-uri documentate; întreabă dacă nu e sigur.
+- Evită variabile globale mutabile; folosește injecție de dependență (constructori de tip NewXxx).
+- Error handling explicit: returnează erori, folosește `errors.Is`/`errors.AsType`.
+- Nu folosi panic pentru control-flow; folosește recover centralizat la boundary-uri HTTP.
+- Aplică backpressure — canale cu buffer limitat, rate-limiter (token bucket), cozi finite.
+- Testează tot: unit tests, integration tests, benchmark-uri și leak tests (goroutineleak profile).
+
+4) Setup & toolchain pentru Go 1.26
+- Instalează Go 1.26 de pe https://go.dev/dl/ (sau managerul preferat). Setează `GOPATH` doar dacă ai nevoie; folosește `go mod`.
+- Inițializează modul:
+  - `go mod init github.com/yourorg/fusee-server`
+  - Asigură `go 1.26` în `go.mod` (editează manual dacă `go mod init` a creat o versiune inferioară)
+- Instrumente recomandate:
+  - `gofmt` (format), `go vet`, `golangci-lint`, `staticcheck`
+  - `go test` + `-race` pentru detecție race conditions
+  - `pprof` (profilare CPU/memorie) și `GOEXPERIMENT=goroutineleakprofile` pentru leak detection în CI/dev
+  - `minio` pentru test local S3, `redis` pentru cache/metadate
+  - `docker` / `kind` / `testcontainers` pentru e2e
+
+5) Structura recomandată proiect
+- cmd/fusee-server/main.go
+- internal/server (HTTP server, middleware)
+- internal/api (handlers, DTO, validation)
+- internal/compile (orchestrare job-uri, queue)
+- internal/worker (worker pool, runners)
+- pkg/storage (S3 adapter), pkg/cache (in-memory + Redis)
+- pkg/observability (metrics/tracing wrappers)
+- test/ (fixtures, golden)
+
+6) Concurența în Go — concepte și pattern-uri esențiale
+- Goroutine: `go fn()` — unitate ușoară de execuție. Nu sunt gratuite.
+- Channel: comunicare sincronă/asincronă între goroutine. Folosește canale buffered pentru backpressure.
+- select: multiplexare pe canale + context.Done() pentru cancel.
+- sync.WaitGroup: sincronizare pentru grupuri de goroutine.
+- sync.Mutex / RWMutex / atomic: folosirea cu atenție când state partajat.
+- errgroup: colectare erori din mai multe goroutine, propagare cancel.
+
+Pattern-uri utile:
+- Worker pool — pentru job-uri compilare.
+- Fan-out/fan-in — paralelizare taskuri independente.
+- Owner-per-shard — pentru a evita lock contention.
+- Circuit breaker + retry with backoff — pentru dependențe instabile.
+
+7) Exemple concrete (cod schematic) — worker pool și orchestration
+- Exemplar worker pool (robust, cu ctx, timeout și wg):
+
+```
+package worker
+
+import (
+    "context"
+    "sync"
+    "time"
+)
+
+type Job struct {
+    ID    string
+    Input []byte
+}
+
+type Result struct {
+    JobID string
+    Err   error
+}
+
+func StartWorkers(ctx context.Context, n int, jobs <-chan Job, results chan<- Result, wg *sync.WaitGroup) {
+    for i := 0; i < n; i++ {
+        wg.Add(1)
+        go func(workerID int) {
+            defer wg.Done()
+            for {
+                select {
+                case <-ctx.Done():
+                    return
+                case job, ok := <-jobs:
+                    if !ok { return }
+                    jobCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
+                    resErr := processJob(jobCtx, job)
+                    cancel()
+                    select {
+                    case results <- Result{JobID: job.ID, Err: resErr}:
+                    case <-ctx.Done():
+                        return
+                    }
+                }
+            }
+        }(i)
+    }
+}
+
+// processJob este funcția de lucru care trebuie să respecte contextul
+func processJob(ctx context.Context, j Job) error {
+    // implementare: build, write artifact to S3, update DB
+    return nil
+}
+```
+
+Observații:
+- Folosește `jobCtx` cu timeout specific pentru fiecare job.
+- Rezultatele pot fi stocate în DB sau trimise pe canal `results`.
+- `wg` este așteptat la shutdown pentru a evita goroutine leaks.
+
+8) HTTP server design & endpoint-uri recomandate
+- Endpoints cheie:
+  - POST /compile → acceptă request, validează, calculează hash input, verifică cache, enquează job asincron și returnează 202 + job_id (sau 200 + artifact dacă e cache hit)
+  - GET /compile/{id}/status → starea jobului
+  - GET /assets/{hash} → serve artifact (WASM/JS) cu headers CDN
+  - /metrics, /debug/pprof/*, /healthz, /readyz
+- Principii handler:
+  - Handlers mici: parse, validate, convert DTO, call service layer, write response
+  - Middleware pentru logging, tracing, recover (panic->500), rate-limit
+
+Exemplu handler schematic:
+
+```
+func (s *Server) compileHandler(w http.ResponseWriter, r *http.Request) {
+    ctx := r.Context()
+    var req CompileRequest
+    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+        http.Error(w, "invalid JSON", http.StatusBadRequest)
+        return
+    }
+    if !s.limiter.Allow() {
+        http.Error(w, "rate limit", http.StatusTooManyRequests)
+        return
+    }
+    key := s.computeHash(req)
+    if art, ok := s.cache.Get(key); ok {
+        w.Header().Set("Content-Type", "application/wasm")
+        w.Write(art)
+        return
+    }
+    jobID, err := s.queue.Enqueue(ctx, req)
+    if err != nil {
+        http.Error(w, "internal", http.StatusInternalServerError)
+        return
+    }
+    w.WriteHeader(http.StatusAccepted)
+    json.NewEncoder(w).Encode(map[string]string{"job_id": jobID})
+}
+```
+
+9) Job orchestration: sync vs async, cache & deduplicare
+- Dev: permită compilare sync cu timeout curat (feedback rapid).
+- Prod: async cu job queue și worker pool; returnează 202. Stochează artefactele în object store.
+- Deduplicare: folosește hash funcțional (deterministic) din input (source + flags) pentru a evita recompilări.
+- Stochează metadate în Redis/DB (status, retrier count, last error, artifact URL).
+
+10) Securitate și izolare
+- Rulează build-runner în containere sandbox (firecracker, gVisor, k8s Jobs) sau procese izolate.
+- Limitările resurselor: cgroup limits, ulimit pentru procese runner.
+- Validare input: never trust client input — sanitize, size limits, timeouts.
+- TLS & auth pentru API, rate-limit per tenant.
+
+11) Observabilitate, tracing și profilare
+- Logging: zap/zerolog (structured logs). Include trace_id, job_id, tenant_id în log fields.
+- Metrics: Prometheus client — counters, histograms (compile_duration_seconds), gauges (job_queue_length).
+- Tracing: OpenTelemetry — trace request flow: HTTP -> queue -> worker -> storage.
+- Profilare: pprof endpoints. Go 1.26 pprof UI default la flamegraph. Activează `goroutineleakprofile` în test/CI pentru leak detection.
+
+12) Testare recomandată
+- Unit tests (table-driven) pentru serviciile pure.
+- Mocks pentru dependințe I/O (storage, redis) cu `github.com/golang/mock` sau `testify/mock`.
+- Integration tests cu MinIO/Redis în container (testcontainers).
+- Golden tests pentru output codgen (compare generated JS/WASM bytes).
+- Differential tests: compară comportamentul JS-based compiler cu runner (Rust/WASM) dacă există.
+- Leak tests: rulează workload mic + colectează goroutineleak profile și asigură că nu apar goroutine leaked.
+
+13) CI/CD și Docker
+- Docker multistage build; folosește `CGO_ENABLED=0` pentru binare statice (dacă nu folosești cgo).
+- GitHub Actions / GitLab CI: lint -> unit tests -> build -> container -> smoke tests (integration), optional: run goroutine leak profile in CI smoke stage.
+- Exemple Dockerfile (multistage):
+
+```
+FROM golang:1.26 AS builder
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /app/cmd/fusee-server ./cmd/fusee-server
+
+FROM gcr.io/distroless/static-debian11
+COPY --from=builder /app/cmd/fusee-server /usr/local/bin/fusee-server
+EXPOSE 8080
+ENTRYPOINT ["/usr/local/bin/fusee-server"]
+```
+
+14) Performanță & optimizări
+- Măsoară cu pprof înainte de optimizare.
+- Evită alocările repetate: folosește `sync.Pool` pentru buffers mari.
+- Sharding pentru a reduce lock contention.
+- Folosește canale pentru coordonare când se potrivește, dar evită blocking pe canale necontrolate.
+- Dacă e nevoie de operații vectorizate, poți explora `simd/archsimd` (experimental) sau implementări native în Rust pentru codgen.
+
+15) Anti-patterns de evitat
+- Goroutine leaks (pornite fără mecanism de oprire).
+- Folosirea `panic` pentru flow control.
+- Variabile globale mutabile pentru state aplicație.
+- Blocking pe canale nebuffered în contexte fără timeout.
+- Ignorarea contextului în apeluri externe.
+
+16) Checklist migrare JS -> Go (server)
+- Definește API contract (OpenAPI)
+- Generare DTO în Go
+- Implementare handlers pure și service layer
+- Job queue + worker pool + cache/dedup
+- Storage artifacts (S3) + CDN headers
+- Observability (metrics, tracing) și health endpoints
+- Security review + sandboxing runner
+- Tests: unit/integration/golden/leak
+
+17) Plan 90 zile (orientativ)
+- Săptămâna 1-2: setup proiect, basic HTTP + middleware, DTO
+- Săptămâna 3-4: implementare job queue simplu, worker pool, sync compile dev mode
+- Săptămâna 5-6: integrate storage (MinIO), cache (Redis), dedup
+- Săptămâna 7-8: add rate limiter, multi-tenant basics, health & metrics
+- Săptămâna 9-10: tracing OTel, pprof, goroutine leak tests în CI
+- Săptămâna 11-12: CI/CD, Docker image, smoke e2e, performance tuning
+
+18) Resurse și linkuri utile
+- Go 1.26 Release Notes: https://go.dev/doc/go1.26
+- Go blog: https://go.dev/blog/go1.26
+- Effective Go: https://go.dev/doc/effective_go
+- golang.org/x/sync/errgroup: https://pkg.go.dev/golang.org/x/sync/errgroup
+- golang.org/x/time/rate: https://pkg.go.dev/golang.org/x/time/rate
+- Prometheus client: https://github.com/prometheus/client_golang
+- OpenTelemetry Go: https://opentelemetry.io/docs/instrumentation/go/
+
+Concluzie
+- Construirea serverului Fusee în Go 1.26 aduce beneficii de performanță, scalabilitate și o experiență solidă de dezvoltare. Folosește `context` pe scară largă, gestionează cu grijă goroutine-urile, instrumentează observabilitatea și asigură izolare pentru runner.
+- Go 1.26 oferă instrumente adiționale (goroutine leak profile, `errors.AsType`, Green Tea GC) care, folosite corect, îți vor ușura munca și îmbunătăți fiabilitatea.
+
+Dacă dorești, pot salva acest fișier ca `ghid_go_fusee_integrat_go1_26.txt` și ți-l pot pune la dispoziție pentru descărcare. De asemenea pot genera o versiune v2 care include un repo template complet (fișiere `main.go`, `server` package, worker example), workflow GitHub Actions și setări `golangci-lint`.