@ecopages/core 0.2.0-alpha.8 → 0.2.1

package/src/router/client/navigation-coordinator.ts

@@ -1,433 +0,0 @@
-/**
- * Shared browser-side navigation coordinator.
- *
- * This module is the client runtime contract used by browser-router,
- * react-router, and HMR code to coordinate ownership, cross-runtime handoff,
- * current-page reloads, and stale-navigation cancellation.
- *
- * The coordinator stays framework-agnostic: browser runtimes register their
- * capabilities here, and the coordinator arbitrates which runtime currently
- * owns the document and which navigation transaction is still current.
- *
- * @module
- */
-
-/** Logical owner name for a browser navigation runtime. */
-export type EcoNavigationOwner = 'none' | 'browser-router' | 'react-router' | (string & {});
-
-/** HTML attribute used to persist the rendered document owner across navigations. */
-export const ECO_DOCUMENT_OWNER_ATTRIBUTE = 'data-eco-document-owner';
-
-/** High-level navigation direction understood by browser runtimes. */
-export type EcoNavigationDirection = 'forward' | 'back' | 'replace';
-
-/** Navigation request sent between browser runtimes. */
-export type EcoNavigationRequest = {
-	href: string;
-	direction?: EcoNavigationDirection;
-	source?: EcoNavigationOwner;
-};
-
-/** Navigation handoff request that includes a pre-fetched document. */
-export type EcoNavigationHandoffRequest = EcoNavigationRequest & {
-	finalHref?: string;
-	targetOwner: EcoNavigationOwner;
-	document: Document;
-	html?: string;
-	/**
-	 * Reports whether the source runtime's original navigation has already been
-	 * superseded.
-	 *
-	 * Target runtimes use this to ignore handoff work that arrives after a newer
-	 * navigation has already claimed ownership.
-	 */
-	isStaleSourceNavigation?: () => boolean;
-};
-
-/** Request to reload the current page through the active runtime. */
-export type EcoReloadRequest = {
-	clearCache?: boolean;
-	source?: EcoNavigationOwner;
-};
-
-/** Snapshot of the coordinator's current runtime ownership state. */
-export type EcoNavigationOwnerState = {
-	owner: EcoNavigationOwner;
-	canHandleSpaNavigation: boolean;
-};
-
-/**
- * Coordinator-managed navigation transaction.
- *
- * Runtimes use this to determine whether async work has become stale and to
- * cancel or complete the active navigation sequence.
- */
-export type EcoNavigationTransaction = {
-	id: number;
-	signal: AbortSignal;
-	isCurrent: () => boolean;
-	cancel: () => void;
-	complete: () => void;
-};
-
-export type EcoNavigationRuntimeEvent =
-	| {
-			type: 'owner-change';
-			owner: EcoNavigationOwner;
-			previousOwner: EcoNavigationOwner;
-			reason: 'set' | 'claim' | 'release' | 'document' | 'unregister';
-	  }
-	| {
-			type: 'registration-change';
-			owner: EcoNavigationOwner;
-			status: 'registered' | 'unregistered';
-	  };
-
-export type EcoNavigationRuntimeListener = (event: EcoNavigationRuntimeEvent) => void;
-
-export type EcoNavigationRuntimeRegistration = {
-	owner: EcoNavigationOwner;
-	navigate?: (request: EcoNavigationRequest) => Promise<boolean | void>;
-	handoffNavigation?: (request: EcoNavigationHandoffRequest) => Promise<boolean | void>;
-	reloadCurrentPage?: (request?: EcoReloadRequest) => Promise<void>;
-	/**
-	 * Releases runtime-owned client state before another runtime commits a new
-	 * document.
-	 *
-	 * This hook intentionally does not run as part of `requestHandoff()`. The
-	 * accepting runtime decides when cleanup is safe so cross-runtime handoffs do
-	 * not blank the current page before the incoming document is ready.
-	 */
-	cleanupBeforeHandoff?: () => void | Promise<void>;
-};
-
-/** Public browser-side navigation coordinator interface. */
-export interface EcoNavigationRuntime {
-	/** Returns the currently active runtime owner and whether it can handle SPA navigation. */
-	getOwnerState(): EcoNavigationOwnerState;
-	/** Starts a new navigation transaction, invalidating the previously active one. */
-	beginNavigationTransaction(): EcoNavigationTransaction;
-	/** Reports whether a navigation transaction is still in flight. */
-	hasPendingNavigationTransaction(): boolean;
-	/** Cancels the active navigation transaction, if one exists. */
-	cancelCurrentNavigationTransaction(): void;
-	/** Forces the current owner value without checking registrations. */
-	setOwner(owner: EcoNavigationOwner): void;
-	/** Claims ownership for a runtime that is ready to drive SPA navigation. */
-	claimOwnership(owner: EcoNavigationOwner): void;
-	/** Releases ownership when the given runtime no longer controls the document. */
-	releaseOwnership(owner: EcoNavigationOwner): void;
-	/** Resolves document ownership from the rendered owner marker or fallback. */
-	resolveDocumentOwner(doc: Document, fallbackOwner?: EcoNavigationOwner): EcoNavigationOwner;
-	/** Reads and adopts the rendered document owner as the active runtime owner. */
-	adoptDocumentOwner(doc: Document, fallbackOwner?: EcoNavigationOwner): EcoNavigationOwner;
-	/** Returns whether the active owner is some runtime other than the given owner. */
-	isOwnedByAnotherRuntime(owner: EcoNavigationOwner): boolean;
-	/** Subscribes to ownership and registration change events. */
-	subscribe(listener: EcoNavigationRuntimeListener): () => void;
-	/** Registers a runtime implementation with the coordinator. */
-	register(runtime: EcoNavigationRuntimeRegistration): () => void;
-	/** Requests navigation through another eligible registered runtime. */
-	requestNavigation(request: EcoNavigationRequest): Promise<boolean>;
-	/**
-	 * Hands a pre-fetched document to the target runtime.
-	 *
-	 * The coordinator delegates the document but does not clean up the current
-	 * owner first. Cleanup timing belongs to the accepting runtime so a stale or
-	 * superseded handoff cannot tear down the current page prematurely.
-	 */
-	requestHandoff(request: EcoNavigationHandoffRequest): Promise<boolean>;
-	/** Requests the active runtime to reload the current page. */
-	reloadCurrentPage(request?: EcoReloadRequest): Promise<boolean>;
-	/** Runs a target runtime's cleanup hook before handoff. */
-	cleanupOwner(owner: EcoNavigationOwner): Promise<void>;
-	/** Runs cleanup for whichever runtime currently owns the document. */
-	cleanupCurrentOwner(): Promise<void>;
-}
-
-/**
- * Reads the explicit browser document owner marker from a rendered HTML document.
- *
- * Documents without a marker return `null`, allowing runtimes to fall back to
- * their local default behavior without scanning hydration scripts.
- */
-export function getEcoDocumentOwner(doc: Document): EcoNavigationOwner | null {
-	const owner = doc.documentElement.getAttribute(ECO_DOCUMENT_OWNER_ATTRIBUTE);
-	return owner && owner.length > 0 ? (owner as EcoNavigationOwner) : null;
-}
-
-type EcoNavigationWindow = Window &
-	typeof globalThis & {
-		__ECO_PAGES__?: {
-			navigation?: EcoNavigationRuntime;
-		};
-	};
-
-function getCandidateOwners(
-	currentOwner: EcoNavigationOwner,
-	registrations: Map<EcoNavigationOwner, EcoNavigationRuntimeRegistration>,
-	excludedOwner?: EcoNavigationOwner,
-): EcoNavigationOwner[] {
-	const owners: EcoNavigationOwner[] = [];
-
-	if (currentOwner !== 'none' && currentOwner !== excludedOwner) {
-		owners.push(currentOwner);
-	}
-
-	for (const owner of registrations.keys()) {
-		if (owner === currentOwner || owner === excludedOwner) {
-			continue;
-		}
-
-		owners.push(owner);
-	}
-
-	return owners;
-}
-
-function createEcoNavigationRuntime(_windowObject: EcoNavigationWindow): EcoNavigationRuntime {
-	const registrations = new Map<EcoNavigationOwner, EcoNavigationRuntimeRegistration>();
-	const listeners = new Set<EcoNavigationRuntimeListener>();
-	let owner: EcoNavigationOwner = 'none';
-	let navigationSequence = 0;
-	let navigationAbortController: AbortController | null = null;
-
-	const emit = (event: EcoNavigationRuntimeEvent) => {
-		for (const listener of listeners) {
-			listener(event);
-		}
-	};
-
-	const updateOwner = (
-		nextOwner: EcoNavigationOwner,
-		reason: Extract<EcoNavigationRuntimeEvent, { type: 'owner-change' }>['reason'],
-	) => {
-		if (owner === nextOwner) {
-			return;
-		}
-
-		const previousOwner = owner;
-		owner = nextOwner;
-		emit({
-			type: 'owner-change',
-			owner: nextOwner,
-			previousOwner,
-			reason,
-		});
-	};
-
-	const cancelNavigationTransaction = (navigationId: number, abortController: AbortController): void => {
-		if (navigationSequence !== navigationId || navigationAbortController !== abortController) {
-			return;
-		}
-
-		navigationSequence += 1;
-		navigationAbortController = null;
-		abortController.abort();
-	};
-
-	const completeNavigationTransaction = (navigationId: number, abortController: AbortController): void => {
-		if (navigationSequence !== navigationId || navigationAbortController !== abortController) {
-			return;
-		}
-
-		navigationAbortController = null;
-	};
-
-	const runtime: EcoNavigationRuntime = {
-		getOwnerState(): EcoNavigationOwnerState {
-			const activeRuntime = registrations.get(owner);
-			return {
-				owner,
-				canHandleSpaNavigation: typeof activeRuntime?.navigate === 'function',
-			};
-		},
-
-		hasPendingNavigationTransaction(): boolean {
-			return navigationAbortController !== null;
-		},
-
-		beginNavigationTransaction(): EcoNavigationTransaction {
-			navigationAbortController?.abort();
-			const abortController = new AbortController();
-			const navigationId = ++navigationSequence;
-			navigationAbortController = abortController;
-
-			return {
-				id: navigationId,
-				signal: abortController.signal,
-				isCurrent: () => navigationSequence === navigationId && navigationAbortController === abortController,
-				cancel: () => {
-					cancelNavigationTransaction(navigationId, abortController);
-				},
-				complete: () => {
-					completeNavigationTransaction(navigationId, abortController);
-				},
-			};
-		},
-
-		cancelCurrentNavigationTransaction(): void {
-			if (!navigationAbortController) {
-				return;
-			}
-
-			cancelNavigationTransaction(navigationSequence, navigationAbortController);
-		},
-
-		setOwner(nextOwner: EcoNavigationOwner): void {
-			updateOwner(nextOwner, 'set');
-		},
-
-		claimOwnership(nextOwner: EcoNavigationOwner): void {
-			updateOwner(nextOwner, 'claim');
-		},
-
-		releaseOwnership(currentOwner: EcoNavigationOwner): void {
-			if (owner !== currentOwner) {
-				return;
-			}
-
-			updateOwner('none', 'release');
-		},
-
-		resolveDocumentOwner(doc: Document, fallbackOwner: EcoNavigationOwner = 'none'): EcoNavigationOwner {
-			return getEcoDocumentOwner(doc) ?? fallbackOwner;
-		},
-
-		adoptDocumentOwner(doc: Document, fallbackOwner: EcoNavigationOwner = 'none'): EcoNavigationOwner {
-			const nextOwner = runtime.resolveDocumentOwner(doc, fallbackOwner);
-			updateOwner(nextOwner, 'document');
-			return nextOwner;
-		},
-
-		isOwnedByAnotherRuntime(candidateOwner: EcoNavigationOwner): boolean {
-			return owner !== 'none' && owner !== candidateOwner;
-		},
-
-		subscribe(listener: EcoNavigationRuntimeListener): () => void {
-			listeners.add(listener);
-			return () => {
-				listeners.delete(listener);
-			};
-		},
-
-		register(registration: EcoNavigationRuntimeRegistration): () => void {
-			registrations.set(registration.owner, registration);
-			emit({
-				type: 'registration-change',
-				owner: registration.owner,
-				status: 'registered',
-			});
-
-			return () => {
-				const currentRegistration = registrations.get(registration.owner);
-				if (currentRegistration !== registration) {
-					return;
-				}
-
-				registrations.delete(registration.owner);
-				emit({
-					type: 'registration-change',
-					owner: registration.owner,
-					status: 'unregistered',
-				});
-				if (owner === registration.owner) {
-					updateOwner('none', 'unregister');
-				}
-			};
-		},
-
-		async requestNavigation(request: EcoNavigationRequest): Promise<boolean> {
-			for (const candidateOwner of getCandidateOwners(owner, registrations, request.source)) {
-				const registration = registrations.get(candidateOwner);
-				if (!registration?.navigate) {
-					continue;
-				}
-
-				const handled = await registration.navigate(request);
-				if (handled !== false) {
-					return true;
-				}
-			}
-
-			return false;
-		},
-
-		async requestHandoff(request: EcoNavigationHandoffRequest): Promise<boolean> {
-			if (request.targetOwner === 'none') {
-				return false;
-			}
-
-			if (request.isStaleSourceNavigation?.()) {
-				return true;
-			}
-
-			const registration = registrations.get(request.targetOwner);
-			if (!registration?.handoffNavigation) {
-				return false;
-			}
-
-			if (request.isStaleSourceNavigation?.()) {
-				return true;
-			}
-
-			const handled = await registration.handoffNavigation(request);
-			return handled !== false;
-		},
-
-		async reloadCurrentPage(request?: EcoReloadRequest): Promise<boolean> {
-			for (const candidateOwner of getCandidateOwners(owner, registrations)) {
-				const registration = registrations.get(candidateOwner);
-				if (!registration?.reloadCurrentPage) {
-					continue;
-				}
-
-				await registration.reloadCurrentPage(request);
-				return true;
-			}
-
-			return false;
-		},
-
-		async cleanupOwner(targetOwner: EcoNavigationOwner): Promise<void> {
-			if (targetOwner === 'none') {
-				return;
-			}
-
-			const registration = registrations.get(targetOwner);
-			if (!registration?.cleanupBeforeHandoff) {
-				return;
-			}
-
-			await registration.cleanupBeforeHandoff();
-			if (owner === targetOwner) {
-				updateOwner('none', 'release');
-			}
-		},
-
-		async cleanupCurrentOwner(): Promise<void> {
-			await runtime.cleanupOwner(owner);
-		},
-	};
-
-	return runtime;
-}
-
-/**
- * Returns the singleton browser-side navigation coordinator.
- *
- * The coordinator centralizes ownership, handoff, and current-page reload
- * requests across browser runtimes through one internal protocol.
- *
- * @param windowObject - Window-like object that stores the singleton runtime.
- * @returns The shared browser navigation coordinator.
- */
-export function getEcoNavigationRuntime(windowObject: Window & typeof globalThis = window): EcoNavigationRuntime {
-	const runtimeWindow = windowObject as EcoNavigationWindow;
-	runtimeWindow.__ECO_PAGES__ = runtimeWindow.__ECO_PAGES__ || {};
-	if (!runtimeWindow.__ECO_PAGES__.navigation) {
-		runtimeWindow.__ECO_PAGES__.navigation = createEcoNavigationRuntime(runtimeWindow);
-	}
-
-	return runtimeWindow.__ECO_PAGES__.navigation;
-}

package/src/router/server/fs-router-scanner.ts

@@ -1,219 +0,0 @@
-import path from 'node:path';
-import { appLogger } from '../../global/app-logger.js';
-import type { EcoPagesAppConfig, RouteKind, Routes } from '../../internal-types.js';
-import type { EcoPageFile, GetStaticPaths } from '../../public-types.js';
-import { fileSystem } from '@ecopages/file-system';
-import { invariant } from '../../utils/invariant.js';
-import { existsSync } from 'node:fs';
-import { getAppServerModuleTranspiler } from '../../services/module-loading/app-server-module-transpiler.service.ts';
-import type { ServerModuleTranspiler } from '../../services/module-loading/server-module-transpiler.service.ts';
-import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.js';
-
-type CreateRouteArgs = {
-	routePath: string;
-	filePath: string;
-	route: string;
-};
-
-type FSRouterScannerOptions = {
-	buildMode: boolean;
-};
-
-/**
- * @class FSRouterScanner
- * @description
- * This class is responsible for scanning the file system for routes.
- * It uses the glob package to scan the file system for files with the specified file extensions.
- * It then creates a map of the routes with the pathname as the key.
- * The pathname is the route without the file extension.
- * For example, if the file is "index.tsx", the pathname will be "/index".
- * If the file is "blog/[slug].tsx", the pathname will be "/blog/[slug]".
- * If the file is "blog/[...slug].tsx", the pathname will be "/blog/[...slug]".
- */
-export class FSRouterScanner {
-	private dir: string;
-	private origin = '';
-	private templatesExt: string[];
-	private options: FSRouterScannerOptions;
-	readonly appConfig: EcoPagesAppConfig;
-	routes: Routes = {};
-	private serverModuleTranspiler: ServerModuleTranspiler;
-
-	constructor({
-		dir,
-		origin,
-		templatesExt,
-		options,
-		appConfig,
-	}: {
-		dir: string;
-		origin: string;
-		templatesExt: string[];
-		options: FSRouterScannerOptions;
-		appConfig: EcoPagesAppConfig;
-	}) {
-		this.dir = dir;
-		this.origin = origin;
-		this.templatesExt = templatesExt;
-		this.options = options;
-		this.appConfig = appConfig;
-		this.serverModuleTranspiler = getAppServerModuleTranspiler(appConfig);
-	}
-
-	private getRoutePath(path: string): string {
-		const cleanedRoute = this.templatesExt
-			.reduce((route, ext) => route.replace(ext, ''), path)
-			.replace(/\/?index$/, '');
-		return `/${cleanedRoute}`;
-	}
-
-	private getDynamicParamsNames(route: string): string[] {
-		const matches = route.match(/\[.*?\]/g);
-		return matches ? matches.map((match) => match.slice(1, -1)) : [];
-	}
-
-	private async getStaticPathsFromDynamicRoute({
-		route,
-		filePath,
-		getStaticPaths,
-	}: {
-		route: string;
-		filePath: string;
-		getStaticPaths: GetStaticPaths;
-	}): Promise<string[]> {
-		const staticPaths = await getStaticPaths({
-			appConfig: this.appConfig,
-			runtimeOrigin: this.origin,
-		});
-		return staticPaths.paths.map((path) => {
-			const dynamicParamsNames = this.getDynamicParamsNames(filePath);
-			let routeWithParams = route;
-
-			for (const param of dynamicParamsNames) {
-				routeWithParams = routeWithParams.replace(`[${param}]`, (path.params as Record<string, string>)[param]);
-			}
-
-			return routeWithParams;
-		});
-	}
-
-	private async createStaticRoutes({
-		filePath,
-		route,
-		routePath,
-		getStaticPaths,
-	}: CreateRouteArgs & { getStaticPaths: GetStaticPaths }): Promise<void> {
-		try {
-			const routesWithParams = await this.getStaticPathsFromDynamicRoute({
-				route,
-				filePath,
-				getStaticPaths,
-			});
-
-			for (const routeWithParams of routesWithParams) {
-				this.createRoute('dynamic', { filePath, route: routeWithParams, routePath });
-			}
-		} catch (error) {
-			appLogger.error(`[ecopages] Error creating static routes for ${filePath}: ${error}`);
-		}
-	}
-
-	private async handleDynamicRouteCreation({ filePath, route, routePath }: CreateRouteArgs): Promise<void> {
-		const module = (await this.importPageModule(filePath)) as EcoPageFile;
-		const Page = module.default;
-
-		/**
-		 * Check for attached static functions (consolidated API) or named exports (legacy)
-		 */
-		const getStaticPaths = Page?.staticPaths ?? module.getStaticPaths;
-		const getStaticProps = Page?.staticProps ?? module.getStaticProps;
-
-		if (this.options.buildMode) {
-			invariant(getStaticProps !== undefined, `[ecopages] Missing getStaticProps in ${filePath}`);
-			invariant(getStaticPaths !== undefined, `[ecopages] Missing getStaticPaths in ${filePath}`);
-		}
-
-		if (getStaticPaths) {
-			return this.createStaticRoutes({
-				filePath,
-				route,
-				routePath,
-				getStaticPaths,
-			});
-		}
-
-		return this.createRoute('dynamic', { filePath, route, routePath });
-	}
-
-	private async importPageModule(filePath: string): Promise<unknown> {
-		return this.serverModuleTranspiler.importModule({
-			filePath,
-			outdir: path.join(resolveInternalExecutionDir(this.appConfig), '.server-route-modules'),
-			externalPackages: false,
-			transpileErrorMessage: (details) => `Error transpiling route module: ${details}`,
-			noOutputMessage: (targetFilePath) => `No transpiled output generated for route module: ${targetFilePath}`,
-		});
-	}
-
-	private createRoute(kind: RouteKind, { filePath, route, routePath }: CreateRouteArgs): void {
-		this.routes[route] = {
-			kind,
-			pathname: routePath,
-			filePath,
-		};
-	}
-
-	private getRouteData(file: string): CreateRouteArgs & {
-		kind: RouteKind;
-	} {
-		const routePath = this.getRoutePath(file);
-		const route = `${this.origin}${routePath}`;
-		const filePath = path.join(this.dir, file);
-		const isCatchAll = filePath.includes('[...');
-		const isDynamic = !isCatchAll && filePath.includes('[') && filePath.includes(']');
-		const kind: RouteKind = isCatchAll ? 'catch-all' : isDynamic ? 'dynamic' : 'exact';
-
-		return { route, routePath, filePath, kind };
-	}
-
-	async scan(): Promise<Routes> {
-		this.routes = {};
-
-		if (!existsSync(this.dir)) {
-			return this.routes;
-		}
-
-		const scannedFiles = await fileSystem.glob(
-			this.templatesExt.map((ext) => `**/*${ext}`),
-			{ cwd: this.dir },
-		);
-
-		for await (const file of scannedFiles) {
-			if (file.includes('.ecopages-node.')) {
-				continue;
-			}
-
-			const { kind, ...routeData } = this.getRouteData(file);
-
-			switch (kind) {
-				case 'dynamic':
-					await this.handleDynamicRouteCreation(routeData);
-					break;
-				case 'catch-all':
-					if (this.options.buildMode) {
-						appLogger.warn(
-							'Catch-all routes are not supported in static generation, they will not be included in the bundle\n',
-							`➤ ${routeData.filePath}`,
-						);
-					}
-					this.createRoute(kind, routeData);
-					break;
-				default:
-					this.createRoute(kind, routeData);
-					break;
-			}
-		}
-
-		return this.routes;
-	}
-}