ezfw-core 1.0.0

package/core/loader.ts

@@ -0,0 +1,725 @@
+import { EzError } from './EzError.js';
+
+export interface ModuleMeta {
+    path: string;
+    defines: string[];
+}
+
+export type ModuleMap = Record<string, () => Promise<unknown>>;
+
+export type LoadPriority = 'high' | 'low' | 'idle';
+
+export type NetworkStrategy = 'fast' | 'medium' | 'slow' | 'offline';
+
+export interface PriorityQueueItem {
+    eztype: string;
+    priority: LoadPriority;
+    resolve: () => void;
+    reject: (err: Error) => void;
+}
+
+export interface RetryConfig {
+    maxRetries: number;
+    baseDelay: number;
+    maxDelay: number;
+}
+
+interface NetworkConnection {
+    effectiveType?: string;
+    saveData?: boolean;
+    addEventListener(event: string, handler: () => void): void;
+}
+
+interface NavigatorWithConnection extends Navigator {
+    connection?: NetworkConnection;
+    mozConnection?: NetworkConnection;
+    webkitConnection?: NetworkConnection;
+}
+
+interface RouteChainItem {
+    path: string;
+    view: string;
+    params: Record<string, string>;
+}
+
+interface RouteMatch {
+    chain: RouteChainItem[];
+    params: Record<string, string>;
+    fullPath: string;
+}
+
+interface EzRouter {
+    _routes: unknown[];
+    _matchRoute(path: string): RouteMatch | null;
+}
+
+interface EzInstance {
+    _registry: Record<string, unknown>;
+    _controllers: Record<string, unknown>;
+    _gridBehaviors: Record<string, unknown>;
+    _models: Record<string, unknown>;
+    _stores: Record<string, unknown>;
+    _context: {
+        route?: string | null;
+        view?: string | null;
+    };
+    _router?: EzRouter;
+    registerComponent(name: string, component: unknown): void;
+}
+
+export class EzLoader {
+    private ez: EzInstance;
+    private _modules: ModuleMap = {};
+    private _moduleIndex: Record<string, string[]> = {};
+    private _moduleMeta: Record<string, ModuleMeta> = {};
+    private _currentModulePath: string | null = null;
+    private _prefetched: Set<string> = new Set();
+    private _prefetchPromises: Map<string, Promise<void>> = new Map();
+    private _lowPriorityQueue: PriorityQueueItem[] = [];
+    private _idlePriorityQueue: PriorityQueueItem[] = [];
+    private _processingQueue: boolean = false;
+    private _idleCallbackId: number | null = null;
+    private _networkStrategy: NetworkStrategy = 'fast';
+    private _networkAware: boolean = false;
+    private _retryConfig: RetryConfig = {
+        maxRetries: 3,
+        baseDelay: 1000,
+        maxDelay: 10000
+    };
+    private _retryAttempts: Map<string, number> = new Map();
+    private _failedModules: Set<string> = new Set();
+
+    constructor(ez: EzInstance) {
+        this.ez = ez;
+        this._initNetworkDetection();
+    }
+
+    private _initNetworkDetection(): void {
+        this._updateNetworkStrategy();
+
+        const nav = navigator as NavigatorWithConnection;
+        const connection = nav.connection || nav.mozConnection || nav.webkitConnection;
+
+        if (connection) {
+            connection.addEventListener('change', () => {
+                this._updateNetworkStrategy();
+            });
+        }
+
+        window.addEventListener('online', () => this._updateNetworkStrategy());
+        window.addEventListener('offline', () => this._updateNetworkStrategy());
+    }
+
+    private _updateNetworkStrategy(): void {
+        if (!navigator.onLine) {
+            this._networkStrategy = 'offline';
+            return;
+        }
+
+        const nav = navigator as NavigatorWithConnection;
+        const connection = nav.connection || nav.mozConnection || nav.webkitConnection;
+
+        if (!connection) {
+            this._networkStrategy = 'fast';
+            return;
+        }
+
+        const effectiveType = connection.effectiveType;
+        const saveData = connection.saveData;
+
+        if (saveData) {
+            this._networkStrategy = 'slow';
+            return;
+        }
+
+        switch (effectiveType) {
+            case 'slow-2g':
+            case '2g':
+                this._networkStrategy = 'slow';
+                break;
+            case '3g':
+                this._networkStrategy = 'medium';
+                break;
+            case '4g':
+            default:
+                this._networkStrategy = 'fast';
+                break;
+        }
+    }
+
+    setNetworkAware(enabled: boolean): void {
+        this._networkAware = enabled;
+    }
+
+    getNetworkStrategy(): NetworkStrategy {
+        return this._networkStrategy;
+    }
+
+    canPrefetch(): boolean {
+        if (!this._networkAware) return true;
+        return this._networkStrategy === 'fast' || this._networkStrategy === 'medium';
+    }
+
+    adjustPriorityForNetwork(requestedPriority: LoadPriority): LoadPriority {
+        if (!this._networkAware) return requestedPriority;
+
+        switch (this._networkStrategy) {
+            case 'offline':
+                return requestedPriority;
+
+            case 'slow':
+                if (requestedPriority === 'low') return 'idle';
+                return requestedPriority;
+
+            case 'medium':
+                return requestedPriority;
+
+            case 'fast':
+            default:
+                return requestedPriority;
+        }
+    }
+
+    getNetworkInfo(): { strategy: NetworkStrategy; online: boolean; effectiveType: string | null; saveData: boolean } {
+        const nav = navigator as NavigatorWithConnection;
+        const connection = nav.connection || nav.mozConnection || nav.webkitConnection;
+
+        return {
+            strategy: this._networkStrategy,
+            online: navigator.onLine,
+            effectiveType: connection?.effectiveType || null,
+            saveData: connection?.saveData || false
+        };
+    }
+
+    installModules(mods: ModuleMap): void {
+        this._modules = mods;
+        this._moduleIndex = {};
+
+        for (const path of Object.keys(mods)) {
+            this._moduleMeta[path] = {
+                path,
+                defines: []
+            };
+            const file = path.split('/').pop();
+            if (!file || (!file.endsWith('.js') && !file.endsWith('.ts'))) continue;
+
+            const eztype = file.replace(/\.(js|ts)$/, '');
+
+            this._moduleIndex[eztype] ??= [];
+            this._moduleIndex[eztype].push(path);
+        }
+
+        for (const eztype in this._moduleIndex) {
+            const paths = this._moduleIndex[eztype];
+            if (paths.length > 1) {
+                throw new EzError({
+                    code: 'EZ_MODULE_DUPLICATE',
+                    source: 'module',
+                    message: `Multiple modules resolve to eztype "${eztype}"`,
+                    details: {
+                        eztype,
+                        modules: paths
+                    }
+                });
+            }
+        }
+    }
+
+    async loadModule(path: string): Promise<unknown> {
+        this._currentModulePath = path;
+        const mod = await this._modules[path]();
+        this._currentModulePath = null;
+        return mod;
+    }
+
+    getCurrentModulePath(): string | null {
+        return this._currentModulePath;
+    }
+
+    getModules(): ModuleMap {
+        return this._modules;
+    }
+
+    getModuleMeta(): Record<string, ModuleMeta> {
+        return this._moduleMeta;
+    }
+
+    async resolveEzType(eztype: string): Promise<void> {
+        if (this.ez._registry[eztype]) return;
+
+        const lowerEztype = eztype.toLowerCase();
+        const keys = Object.keys(this._modules);
+
+        const path = keys.find(p => {
+            const filename = p.split(/[/\\]/).pop()?.toLowerCase() || '';
+            return filename === `${lowerEztype}.js` || filename === `${lowerEztype}.ts`;
+        });
+
+        if (!path) {
+            return;
+        }
+
+        const module = await this.loadModuleWithRetry(path) as Record<string, unknown>;
+
+        let exported = module.default || Object.values(module).find(v => typeof v === 'function');
+
+        if (!exported) {
+            exported = this.ez._registry[eztype] as Record<string, unknown> | undefined;
+        }
+
+        if (!exported) {
+            throw new Error(`[ez] Module loaded for ${eztype} but exports no class/function or ez.define`);
+        }
+
+        this.ez.registerComponent(eztype, exported);
+    }
+
+    async resolveController(name: string | object | null): Promise<unknown> {
+        if (!name) return null;
+
+        if (typeof name === 'object') {
+            return name;
+        }
+
+        if (this.ez._controllers[name]) return this.ez._controllers[name];
+
+        const controllerName = name.endsWith('Controller') ? name : `${name}Controller`;
+
+        if (this.ez._controllers[controllerName]) {
+            if (name !== controllerName) {
+                this.ez._controllers[name] = this.ez._controllers[controllerName];
+            }
+            return this.ez._controllers[controllerName];
+        }
+
+        const lower = controllerName.toLowerCase();
+
+        const path = Object.keys(this._modules).find(p => {
+            const filename = p.split('/').pop()?.toLowerCase() || '';
+            return filename === `${lower}.js` || filename === `${lower}.ts`;
+        });
+
+        if (!path) {
+            throw new EzError({
+                code: 'EZ_CONTROLLER_404',
+                source: 'controller',
+                message: `Controller "${controllerName}" not found`,
+                route: this.ez._context.route,
+                view: this.ez._context.view,
+                details: {
+                    requested: name,
+                    inferred: controllerName,
+                    available: Object.keys(this.ez._controllers)
+                }
+            });
+        }
+
+        await this.loadModuleWithRetry(path);
+
+        if (name !== controllerName && this.ez._controllers[controllerName]) {
+            this.ez._controllers[name] = this.ez._controllers[controllerName];
+        }
+
+        return this.ez._controllers[controllerName];
+    }
+
+    async resolveGridBehavior(name: string): Promise<void> {
+        if (!name) return;
+        if (this.ez._gridBehaviors[name]) return;
+
+        const lower = name.toLowerCase();
+
+        const path = Object.keys(this._modules).find(
+            p => p.toLowerCase().includes(lower)
+        );
+
+        if (!path) {
+            throw new EzError({
+                code: 'EZ_GRID_BEHAVIOR_404',
+                source: 'grid',
+                message: `GridBehavior "${name}" not found`,
+                route: this.ez._context?.route,
+                view: this.ez._context?.view
+            });
+        }
+
+        await this.loadModuleWithRetry(path);
+    }
+
+    async resolveModel(name: string): Promise<void> {
+        if (!name) return;
+        if (this.ez._models[name]) return;
+
+        const lower = name.toLowerCase();
+
+        const path = Object.keys(this._modules).find(p => {
+            const filename = p.split('/').pop()?.toLowerCase() || '';
+            return filename === `${lower}.js` || filename === `${lower}.ts`;
+        });
+
+        if (!path) {
+            throw new EzError({
+                code: 'EZ_MODEL_404',
+                source: 'model',
+                message: `Model "${name}" not found`,
+                route: this.ez._context?.route,
+                view: this.ez._context?.view,
+                details: {
+                    requested: name,
+                    available: Object.keys(this.ez._models)
+                }
+            });
+        }
+
+        await this.loadModuleWithRetry(path);
+    }
+
+    async resolveStore(name: string): Promise<void> {
+        if (!name) return;
+        if (this.ez._stores[name]) return;
+
+        const lower = name.toLowerCase();
+
+        const path = Object.keys(this._modules).find(p => {
+            const filename = p.split('/').pop()?.toLowerCase() || '';
+            return filename === `${lower}.js` || filename === `${lower}.ts`;
+        });
+
+        if (!path) {
+            throw new EzError({
+                code: 'EZ_STORE_404',
+                source: 'store',
+                message: `Store "${name}" not found`,
+                route: this.ez._context?.route,
+                view: this.ez._context?.view,
+                details: {
+                    requested: name,
+                    available: Object.keys(this.ez._stores)
+                }
+            });
+        }
+
+        await this.loadModuleWithRetry(path);
+    }
+
+    async loadCss(path: string): Promise<void> {
+        if (!path) return;
+
+        if (document.querySelector(`link[data-ez-css="${path}"]`)) return;
+
+        const link = document.createElement('link');
+        link.rel = 'stylesheet';
+        link.href = path;
+        link.setAttribute('data-ez-css', path);
+        document.head.appendChild(link);
+    }
+
+    async prefetch(eztype: string): Promise<void> {
+        if (!this.canPrefetch()) return;
+
+        if (this.ez._registry[eztype]) return;
+
+        const path = this._findModulePath(eztype);
+        if (!path) return;
+
+        if (this._prefetched.has(path)) return;
+
+        if (this._prefetchPromises.has(path)) {
+            return this._prefetchPromises.get(path);
+        }
+
+        const idle = window.requestIdleCallback || ((cb: () => void) => setTimeout(cb, 1) as unknown as number);
+
+        const promise = new Promise<void>((resolve) => {
+            idle(async () => {
+                try {
+                    await this.loadModule(path);
+                    this._prefetched.add(path);
+                } catch {
+                    // Silently fail - prefetch is best-effort
+                }
+                this._prefetchPromises.delete(path);
+                resolve();
+            });
+        });
+
+        this._prefetchPromises.set(path, promise);
+        return promise;
+    }
+
+    async prefetchAll(eztypes: string[]): Promise<void> {
+        await Promise.all(eztypes.map(t => this.prefetch(t)));
+    }
+
+    private _findModulePath(eztype: string): string | null {
+        const lowerEztype = eztype.toLowerCase();
+        const keys = Object.keys(this._modules);
+
+        return keys.find(p => {
+            const filename = p.split(/[/\\]/).pop()?.toLowerCase() || '';
+            return filename === `${lowerEztype}.js` || filename === `${lowerEztype}.ts`;
+        }) || null;
+    }
+
+    isPrefetched(eztype: string): boolean {
+        const path = this._findModulePath(eztype);
+        return path ? this._prefetched.has(path) : false;
+    }
+
+    async loadWithPriority(eztype: string, priority: LoadPriority = 'high'): Promise<void> {
+        if (this.ez._registry[eztype]) return;
+
+        const adjustedPriority = this.adjustPriorityForNetwork(priority);
+
+        if (adjustedPriority === 'high') {
+            return this.resolveEzType(eztype);
+        }
+
+        return new Promise((resolve, reject) => {
+            const item: PriorityQueueItem = { eztype, priority: adjustedPriority, resolve, reject };
+
+            if (adjustedPriority === 'low') {
+                this._lowPriorityQueue.push(item);
+                this._scheduleLowPriorityProcessing();
+            } else if (adjustedPriority === 'idle') {
+                this._idlePriorityQueue.push(item);
+                this._scheduleIdleProcessing();
+            }
+        });
+    }
+
+    private _scheduleLowPriorityProcessing(): void {
+        if (this._processingQueue) return;
+
+        setTimeout(() => this._processLowPriorityQueue(), 0);
+    }
+
+    private async _processLowPriorityQueue(): Promise<void> {
+        if (this._processingQueue) return;
+        if (this._lowPriorityQueue.length === 0) return;
+
+        this._processingQueue = true;
+
+        while (this._lowPriorityQueue.length > 0) {
+            const item = this._lowPriorityQueue.shift();
+            if (!item) continue;
+
+            try {
+                await this.resolveEzType(item.eztype);
+                item.resolve();
+            } catch (err) {
+                item.reject(err as Error);
+            }
+        }
+
+        this._processingQueue = false;
+    }
+
+    private _scheduleIdleProcessing(): void {
+        if (this._idleCallbackId !== null) return;
+
+        const idle = window.requestIdleCallback || ((cb: (deadline: IdleDeadline) => void) => setTimeout(() => cb({ timeRemaining: () => 50, didTimeout: false }), 50) as unknown as number);
+
+        this._idleCallbackId = idle((deadline: IdleDeadline) => {
+            this._idleCallbackId = null;
+            this._processIdleQueue(deadline);
+        });
+    }
+
+    private async _processIdleQueue(deadline: IdleDeadline): Promise<void> {
+        while (this._idlePriorityQueue.length > 0 && deadline.timeRemaining() > 5) {
+            const item = this._idlePriorityQueue.shift();
+            if (!item) continue;
+
+            try {
+                await this.resolveEzType(item.eztype);
+                item.resolve();
+            } catch (err) {
+                item.reject(err as Error);
+            }
+        }
+
+        if (this._idlePriorityQueue.length > 0) {
+            this._scheduleIdleProcessing();
+        }
+    }
+
+    getPendingCount(): { low: number; idle: number } {
+        return {
+            low: this._lowPriorityQueue.length,
+            idle: this._idlePriorityQueue.length
+        };
+    }
+
+    setRetryConfig(config: Partial<RetryConfig>): void {
+        this._retryConfig = { ...this._retryConfig, ...config };
+    }
+
+    async loadModuleWithRetry(path: string): Promise<unknown> {
+        if (this._failedModules.has(path)) {
+            throw new Error(`Module "${path}" has permanently failed to load`);
+        }
+
+        const { maxRetries, baseDelay, maxDelay } = this._retryConfig;
+        let lastError: Error | undefined;
+
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                this._retryAttempts.set(path, attempt);
+
+                const module = await this.loadModule(path);
+
+                this._retryAttempts.delete(path);
+                return module;
+
+            } catch (err) {
+                lastError = err as Error;
+
+                if (!navigator.onLine) {
+                    throw err;
+                }
+
+                if (attempt >= maxRetries) {
+                    this._failedModules.add(path);
+                    this._retryAttempts.delete(path);
+                    throw err;
+                }
+
+                const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+
+                const jitter = delay * 0.2 * (Math.random() - 0.5);
+                const finalDelay = Math.round(delay + jitter);
+
+                await this._sleep(finalDelay);
+            }
+        }
+
+        throw lastError;
+    }
+
+    private _sleep(ms: number): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+
+    getRetryStatus(path: string): { attempts: number; failed: boolean } | null {
+        if (this._failedModules.has(path)) {
+            return { attempts: this._retryConfig.maxRetries + 1, failed: true };
+        }
+
+        const attempts = this._retryAttempts.get(path);
+        if (attempts !== undefined) {
+            return { attempts, failed: false };
+        }
+
+        return null;
+    }
+
+    clearFailedModule(path: string): void {
+        this._failedModules.delete(path);
+        this._retryAttempts.delete(path);
+    }
+
+    clearAllFailedModules(): void {
+        this._failedModules.clear();
+        this._retryAttempts.clear();
+    }
+
+    getFailedModules(): string[] {
+        return [...this._failedModules];
+    }
+
+    addPreloadHint(eztype: string): boolean {
+        if (!this.canPrefetch()) return false;
+
+        if (this.ez._registry[eztype]) return false;
+
+        const path = this._findModulePath(eztype);
+        if (!path) return false;
+
+        return this._injectPreloadLink(path);
+    }
+
+    addPreloadHints(eztypes: string[]): number {
+        let count = 0;
+        for (const eztype of eztypes) {
+            if (this.addPreloadHint(eztype)) count++;
+        }
+        return count;
+    }
+
+    private _injectPreloadLink(path: string): boolean {
+        const selector = `link[rel="modulepreload"][href="${path}"]`;
+        if (document.querySelector(selector)) return false;
+
+        const link = document.createElement('link');
+        link.rel = 'modulepreload';
+        link.href = path;
+        link.setAttribute('data-ez-preload', 'true');
+
+        document.head.appendChild(link);
+        return true;
+    }
+
+    async addPreloadHintsForRoute(routePath: string): Promise<number> {
+        if (!this.canPrefetch()) return 0;
+
+        const router = this.ez._router;
+        if (!router) return 0;
+
+        const match = router._matchRoute(routePath.toLowerCase());
+        if (!match || !match.chain.length) return 0;
+
+        const views = match.chain.map(r => r.view).filter(Boolean);
+        return this.addPreloadHints(views);
+    }
+
+    async addPreloadHintsForAdjacentRoutes(): Promise<number> {
+        if (!this.canPrefetch()) return 0;
+
+        const router = this.ez._router;
+        if (!router || !router._routes) return 0;
+
+        const currentPath = window.location.pathname;
+        let count = 0;
+
+        interface RouteNode {
+            path: string;
+            view?: string;
+            children?: RouteNode[];
+        }
+
+        const collectAdjacent = (routes: RouteNode[], parentPath: string = ''): void => {
+            for (const route of routes) {
+                const fullPath = parentPath + route.path;
+
+                if (fullPath === currentPath) {
+                    if (route.children) {
+                        for (const child of route.children) {
+                            if (child.view) {
+                                if (this.addPreloadHint(child.view)) count++;
+                            }
+                        }
+                    }
+                    continue;
+                }
+
+                if (route.view) {
+                    if (this.addPreloadHint(route.view)) count++;
+                }
+            }
+        };
+
+        collectAdjacent(router._routes as RouteNode[]);
+        return count;
+    }
+
+    clearPreloadHints(): void {
+        const links = document.querySelectorAll('link[data-ez-preload="true"]');
+        links.forEach(link => link.remove());
+    }
+
+    getPreloadHintCount(): number {
+        return document.querySelectorAll('link[data-ez-preload="true"]').length;
+    }
+}