ezfw-core 1.0.0

package/core/router.ts

@@ -0,0 +1,490 @@
+import { EzError } from './EzError.js';
+
+export interface NavigationContext {
+    from: string;
+    to: string;
+    params: Record<string, string>;
+    match: RouteMatch | null;
+    meta: Record<string, unknown>;
+}
+
+export type MiddlewareFunction = (context: NavigationContext, next: () => Promise<void>) => Promise<void> | void;
+
+export interface RouteDefinition {
+    path: string;
+    view: string;
+    protected?: (string | (() => boolean | Promise<boolean>))[];
+    children?: RouteDefinition[];
+    middleware?: MiddlewareFunction[];
+    meta?: Record<string, unknown>;
+}
+
+export interface NormalizedRoute {
+    path: string;
+    view: string;
+    protected: (string | (() => boolean | Promise<boolean>))[];
+    children: NormalizedRoute[];
+    middleware: MiddlewareFunction[];
+    meta: Record<string, unknown>;
+}
+
+export interface RouteChainItem {
+    path: string;
+    view: string;
+    params: Record<string, string>;
+}
+
+export interface RouteMatch {
+    chain: RouteChainItem[];
+    params: Record<string, string>;
+    fullPath: string;
+}
+
+export interface RouteInfo {
+    path: string;
+    params: Record<string, string>;
+}
+
+type ErrorHandler = (error: Error, context: NavigationContext) => void;
+
+interface ControllerInstance {
+    onRouteChange?: (info: { fullPath: string; params: Record<string, string>; chain: RouteChainItem[] }) => Promise<void>;
+    [key: string]: unknown;
+}
+
+interface EzInstance {
+    _context: {
+        route?: string | null;
+        view?: string | null;
+        controller?: string | null;
+    };
+    _loader: {
+        getModules(): Record<string, unknown>;
+        loadModule(path: string): Promise<void>;
+        resolveEzType(name: string): Promise<void>;
+        prefetchAll(views: string[]): Promise<void>;
+    };
+    _registry: Record<string, { controller?: string; [key: string]: unknown }>;
+    _eventBus?: {
+        emit(event: string, data: unknown): void;
+    };
+    get(name: string): unknown;
+    getController(name: string): Promise<ControllerInstance>;
+    _createElement(config: unknown): Promise<HTMLElement>;
+    handleFrameworkError(error: Error): void;
+}
+
+export class EzRouter {
+    private ez: EzInstance;
+    private _routes: NormalizedRoute[] = [];
+    private _currentLayoutKey: string | null = null;
+    private _currentPath: string = '/';
+    private _beforeMiddleware: MiddlewareFunction[] = [];
+    private _afterMiddleware: MiddlewareFunction[] = [];
+    private _errorHandlers: ErrorHandler[] = [];
+    private _navigating: boolean = false;
+
+    constructor(ez: EzInstance) {
+        this.ez = ez;
+    }
+
+    routes(routeDefs: RouteDefinition[]): void {
+        if (!Array.isArray(routeDefs)) {
+            console.error('[ez.routes] Must receive an array of route definitions.');
+            return;
+        }
+
+        const normalize = (r: RouteDefinition): NormalizedRoute => ({
+            path: r.path || '/',
+            view: r.view,
+            protected: r.protected || [],
+            children: Array.isArray(r.children)
+                ? r.children.map(normalize)
+                : [],
+            middleware: r.middleware || [],
+            meta: r.meta || {}
+        });
+
+        this._routes = routeDefs.map(normalize);
+    }
+
+    beforeEach(fn: MiddlewareFunction): () => void {
+        if (typeof fn !== 'function') {
+            throw new Error('[EzRouter] Middleware must be a function');
+        }
+        this._beforeMiddleware.push(fn);
+        return () => {
+            const idx = this._beforeMiddleware.indexOf(fn);
+            if (idx > -1) this._beforeMiddleware.splice(idx, 1);
+        };
+    }
+
+    afterEach(fn: MiddlewareFunction): () => void {
+        if (typeof fn !== 'function') {
+            throw new Error('[EzRouter] Middleware must be a function');
+        }
+        this._afterMiddleware.push(fn);
+        return () => {
+            const idx = this._afterMiddleware.indexOf(fn);
+            if (idx > -1) this._afterMiddleware.splice(idx, 1);
+        };
+    }
+
+    onError(fn: ErrorHandler): () => void {
+        if (typeof fn !== 'function') {
+            throw new Error('[EzRouter] Error handler must be a function');
+        }
+        this._errorHandlers.push(fn);
+        return () => {
+            const idx = this._errorHandlers.indexOf(fn);
+            if (idx > -1) this._errorHandlers.splice(idx, 1);
+        };
+    }
+
+    private async _runMiddlewareChain(middlewares: MiddlewareFunction[], context: NavigationContext): Promise<boolean> {
+        if (!middlewares.length) return true;
+
+        let index = 0;
+        let completed = false;
+
+        const next = async (): Promise<void> => {
+            if (index >= middlewares.length) {
+                completed = true;
+                return;
+            }
+
+            const middleware = middlewares[index++];
+
+            try {
+                await middleware(context, next);
+            } catch (err) {
+                this._handleNavigationError(err as Error, context);
+                throw err;
+            }
+        };
+
+        try {
+            await next();
+            return completed;
+        } catch {
+            return false;
+        }
+    }
+
+    private _handleNavigationError(error: Error, context: NavigationContext): void {
+        if (this._errorHandlers.length) {
+            for (const handler of this._errorHandlers) {
+                try {
+                    handler(error, context);
+                } catch (e) {
+                    console.error('[EzRouter] Error in error handler:', e);
+                }
+            }
+        } else {
+            this.ez.handleFrameworkError(error);
+        }
+    }
+
+    go(path: string): void {
+        const clean = path || '/';
+
+        window.history.pushState({}, '', clean);
+
+        this._onLocationChange().catch(err => {
+            this.ez.handleFrameworkError(err);
+        });
+    }
+
+    async navigate(viewName: string, route: RouteInfo | null = null): Promise<void> {
+        this.ez._context.view = viewName;
+        this.ez._context.route = route?.path ?? null;
+        this.ez._context.controller = null;
+
+        const modules = this.ez._loader.getModules();
+        const path = Object.keys(modules).find(p =>
+            p.toLowerCase().includes(`/${viewName.toLowerCase()}/`)
+            || p.toLowerCase().endsWith(`/${viewName.toLowerCase()}.js`)
+        );
+
+        if (!path) {
+            throw new EzError({
+                code: 'EZ_VIEW_404',
+                source: 'router',
+                message: `View "${viewName}" not found`,
+                route: this.ez._context.route,
+                view: viewName
+            });
+        }
+
+        await this.ez._loader.loadModule(path);
+
+        const def = this.ez.get(viewName);
+        if (!def) {
+            throw new EzError({
+                code: 'EZ_VIEW_404',
+                source: 'router',
+                message: `View "${viewName}" not found`,
+                route: this.ez._context.route,
+                view: viewName
+            });
+        }
+
+        const config = {
+            eztype: viewName,
+            route,
+            routeParams: route?.params
+        };
+
+        const root = document.getElementById('app');
+        if (!root) return;
+
+        root.querySelectorAll('*').forEach(node => {
+            const inst = (node as unknown as { __ezInstance?: { destroy?: () => void } }).__ezInstance;
+            if (inst && typeof inst.destroy === 'function') {
+                inst.destroy();
+            }
+        });
+
+        root.innerHTML = '';
+
+        const el = await this.ez._createElement(config);
+        root.appendChild(el);
+    }
+
+    private _matchRoute(path: string): RouteMatch | null {
+        const clean = path.replace(/\/+$/, '') || '/';
+        const segments = clean.split('/').filter(Boolean);
+
+        for (const route of this._routes) {
+            const match = this._matchRouteNode(route, segments, []);
+            if (match) return match;
+        }
+
+        return null;
+    }
+
+    private _matchRouteNode(
+        route: NormalizedRoute,
+        segments: string[],
+        chain: RouteChainItem[],
+        parentParams: Record<string, string> = {}
+    ): RouteMatch | null {
+        const routeSegments = route.path
+            .replace(/^\/+/, '')
+            .split('/')
+            .filter(Boolean);
+
+        if (routeSegments.length > segments.length) return null;
+
+        const params: Record<string, string> = { ...parentParams };
+
+        for (let i = 0; i < routeSegments.length; i++) {
+            const r = routeSegments[i];
+            const s = segments[i];
+
+            if (r.startsWith(':')) {
+                params[r.slice(1)] = decodeURIComponent(s);
+            } else if (r.toLowerCase() !== s.toLowerCase()) {
+                return null;
+            }
+        }
+
+        const consumed = routeSegments.length;
+        const nextSegments = segments.slice(consumed);
+
+        const nextChain: RouteChainItem[] = [
+            ...chain,
+            { path: route.path, view: route.view, params }
+        ];
+
+        if (!nextSegments.length) {
+            return {
+                chain: nextChain,
+                params,
+                fullPath: '/' + segments.join('/')
+            };
+        }
+
+        if (route.children) {
+            for (const child of route.children) {
+                const childMatch = this._matchRouteNode(
+                    child,
+                    nextSegments,
+                    nextChain,
+                    params
+                );
+                if (childMatch) return childMatch;
+            }
+        }
+
+        return null;
+    }
+
+    private async _onLocationChange(): Promise<void> {
+        if (this._navigating) return;
+        this._navigating = true;
+
+        const fromPath = this._currentPath;
+        const toPath = window.location.pathname || '/';
+
+        try {
+            const match = this._matchRoute(toPath);
+            if (!match) {
+                throw new EzError({
+                    code: 'EZ_ROUTER_404',
+                    source: 'router',
+                    message: `No route matched "${toPath}"`,
+                    route: toPath
+                });
+            }
+
+            const { chain } = match;
+            if (!chain.length) return;
+
+            const root = chain[0];
+            const children = chain.slice(1);
+
+            const routeDef = this._routes.find(r => r.view === root.view);
+
+            const context: NavigationContext = {
+                from: fromPath,
+                to: toPath,
+                params: match.params,
+                match,
+                meta: routeDef?.meta || {}
+            };
+
+            const beforeOk = await this._runMiddlewareChain(
+                this._beforeMiddleware,
+                context
+            );
+            if (!beforeOk) return;
+
+            if (routeDef?.middleware?.length) {
+                const routeOk = await this._runMiddlewareChain(
+                    routeDef.middleware,
+                    context
+                );
+                if (!routeOk) return;
+            }
+
+            this.ez._context.route = toPath;
+            this.ez._context.view = root.view;
+
+            if (routeDef?.protected?.length) {
+                for (const rule of routeDef.protected) {
+                    const ok = await this._resolveProtectedCheck(rule);
+                    if (!ok) {
+                        this.go('/');
+                        return;
+                    }
+                }
+            }
+
+            if (this._currentLayoutKey !== root.view) {
+                this._currentLayoutKey = root.view;
+                await this.navigate(root.view, {
+                    path: root.path,
+                    params: root.params
+                });
+            }
+
+            const controllerName = await this._resolveControllerFromView(root.view);
+            if (controllerName) {
+                const ctrl = await this.ez.getController(controllerName);
+                await ctrl?.onRouteChange?.({
+                    fullPath: toPath,
+                    params: match.params,
+                    chain: children
+                });
+            }
+
+            this._currentPath = toPath;
+
+            await this._runMiddlewareChain(this._afterMiddleware, context);
+
+            this.ez._eventBus?.emit('route:change', context);
+
+        } finally {
+            this._navigating = false;
+        }
+    }
+
+    private async _resolveProtectedCheck(str: string | (() => boolean | Promise<boolean>)): Promise<boolean> {
+        if (typeof str === 'function') {
+            return str();
+        }
+
+        const parts = str.split(':');
+        if (parts.length < 2) return false;
+
+        const controllerName = parts[0];
+        const methodAndArgs = parts[1].split('.');
+
+        const method = methodAndArgs[0];
+        const args = methodAndArgs.slice(1);
+
+        const controller = await this.ez.getController(controllerName);
+        if (!controller) return false;
+
+        const fn = controller[method];
+        if (typeof fn !== 'function') {
+            throw new EzError({
+                code: 'EZ_GUARD_001',
+                source: 'router',
+                message: `Guard method "${method}" not found on controller "${controllerName}"`,
+                route: this.ez._context.route,
+                view: this.ez._context.view,
+                details: {
+                    controller: controllerName,
+                    method,
+                    available: Object.keys(controller)
+                }
+            });
+        }
+
+        return await (fn as (...args: string[]) => Promise<boolean>).apply(controller, args);
+    }
+
+    private async _resolveControllerFromView(viewName: string): Promise<string | null> {
+        if (!viewName) return null;
+
+        await this.ez._loader.resolveEzType(viewName);
+        const def = this.ez._registry[viewName];
+        if (!def || typeof def !== 'object') return null;
+
+        return def.controller || null;
+    }
+
+    installPopStateListener(): void {
+        window.addEventListener('popstate', () => {
+            this._onLocationChange().catch(err => {
+                this.ez.handleFrameworkError(err);
+            });
+        });
+    }
+
+    async prefetch(path: string): Promise<void> {
+        const match = this._matchRoute(path);
+        if (!match || !match.chain.length) return;
+
+        const views = match.chain.map(r => r.view).filter(Boolean);
+        await this.ez._loader.prefetchAll(views);
+    }
+
+    enableLinkPrefetch(): void {
+        document.addEventListener('pointerenter', (e) => {
+            const link = (e.target as HTMLElement).closest('a[href]');
+            if (!link) return;
+
+            const href = link.getAttribute('href');
+            if (!href) return;
+
+            if (!href.startsWith('/')) return;
+
+            if (link.hasAttribute('data-no-prefetch')) return;
+
+            this.prefetch(href);
+        }, { capture: true, passive: true });
+    }
+}

package/core/services.ts

@@ -0,0 +1,124 @@
+import { RouteUIService } from '../services/RouteUI.js';
+import { FetchApi } from '../services/fetchApi.js';
+import { EzDialogService } from '../services/dialog.js';
+import { EzToastService } from '../services/toast.js';
+
+interface FirebaseConfig {
+    apiKey: string;
+    authDomain: string;
+    projectId: string;
+}
+
+interface FirebaseService {
+    init(): Promise<void>;
+    [key: string]: unknown;
+}
+
+interface CryptoServiceType {
+    init(secret: string): Promise<void>;
+    [key: string]: unknown;
+}
+
+interface EzInstance {
+    [key: string]: unknown;
+}
+
+export class EzServices {
+    private ez: EzInstance;
+    private _firebase: FirebaseService | null = null;
+    private _api: FetchApi | null = null;
+    private _crypto: CryptoServiceType | null = null;
+    private _routeUI: RouteUIService | null = null;
+    private _dialog: EzDialogService | null = null;
+    private _toast: EzToastService | null = null;
+    private _initialized: boolean = false;
+
+    constructor(ez: EzInstance) {
+        this.ez = ez;
+    }
+
+    async init(): Promise<void> {
+        if (this._initialized) return;
+
+        await Promise.all([
+            this._initRouteUI(),
+            this._initApi(),
+            this._initCrypto(),
+            this._initFirebase(),
+            this._initDialog(),
+            this._initToast()
+        ]);
+
+        this._initialized = true;
+    }
+
+    private _initRouteUI(): void {
+        this._routeUI = new RouteUIService();
+    }
+
+    get routeUI(): RouteUIService | null {
+        return this._routeUI;
+    }
+
+    private _initApi(): void {
+        this._api = new FetchApi({
+            baseUrl: (import.meta as unknown as { env: Record<string, string> }).env.VITE_API_BASE_URL || ''
+        });
+    }
+
+    get api(): FetchApi | null {
+        return this._api;
+    }
+
+    private async _initCrypto(): Promise<void> {
+        const env = (import.meta as unknown as { env: Record<string, string> }).env;
+        if (!env.VITE_CRYPTO_SECRET) {
+            return;
+        }
+
+        const { CryptoService } = await import('../services/crypto.js');
+        await CryptoService.init(env.VITE_CRYPTO_SECRET);
+        this._crypto = CryptoService;
+    }
+
+    get crypto(): CryptoServiceType | null {
+        return this._crypto;
+    }
+
+    private async _initFirebase(): Promise<void> {
+        const env = (import.meta as unknown as { env: Record<string, string> }).env;
+        if (env.VITE_USE_FIREBASE !== 'true') {
+            return;
+        }
+
+        const firebaseConfig: FirebaseConfig = {
+            apiKey: env.VITE_FIREBASE_API_KEY,
+            authDomain: env.VITE_FIREBASE_AUTH_DOMAIN,
+            projectId: env.VITE_FIREBASE_PROJECT_ID,
+        };
+
+        const { FirebaseService } = await import('../services/firebase.js');
+        this._firebase = new FirebaseService(firebaseConfig) as unknown as FirebaseService;
+        await this._firebase!.init();
+    }
+
+    get firebase(): FirebaseService | null {
+        return this._firebase;
+    }
+
+    private _initDialog(): void {
+        this._dialog = new EzDialogService();
+    }
+
+    get dialog(): EzDialogService | null {
+        return this._dialog;
+    }
+
+    private _initToast(): void {
+        this._toast = new EzToastService();
+    }
+
+    get toast(): EzToastService | null {
+        return this._toast;
+    }
+}