@ecopages/core 0.2.0-alpha.8 → 0.2.1-beta.0

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.d.ts

@@ -1,41 +0,0 @@
-import type { EcoPagesAppConfig, Routes } from '../../internal-types.js';
-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 declare class FSRouterScanner {
-    private dir;
-    private origin;
-    private templatesExt;
-    private options;
-    readonly appConfig: EcoPagesAppConfig;
-    routes: Routes;
-    private serverModuleTranspiler;
-    constructor({ dir, origin, templatesExt, options, appConfig, }: {
-        dir: string;
-        origin: string;
-        templatesExt: string[];
-        options: FSRouterScannerOptions;
-        appConfig: EcoPagesAppConfig;
-    });
-    private getRoutePath;
-    private getDynamicParamsNames;
-    private getStaticPathsFromDynamicRoute;
-    private createStaticRoutes;
-    private handleDynamicRouteCreation;
-    private importPageModule;
-    private createRoute;
-    private getRouteData;
-    scan(): Promise<Routes>;
-}
-export {};

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

@@ -1,156 +0,0 @@
-import path from "node:path";
-import { appLogger } from "../../global/app-logger.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.js";
-import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
-class FSRouterScanner {
-  dir;
-  origin = "";
-  templatesExt;
-  options;
-  appConfig;
-  routes = {};
-  serverModuleTranspiler;
-  constructor({
-    dir,
-    origin,
-    templatesExt,
-    options,
-    appConfig
-  }) {
-    this.dir = dir;
-    this.origin = origin;
-    this.templatesExt = templatesExt;
-    this.options = options;
-    this.appConfig = appConfig;
-    this.serverModuleTranspiler = getAppServerModuleTranspiler(appConfig);
-  }
-  getRoutePath(path2) {
-    const cleanedRoute = this.templatesExt.reduce((route, ext) => route.replace(ext, ""), path2).replace(/\/?index$/, "");
-    return `/${cleanedRoute}`;
-  }
-  getDynamicParamsNames(route) {
-    const matches = route.match(/\[.*?\]/g);
-    return matches ? matches.map((match) => match.slice(1, -1)) : [];
-  }
-  async getStaticPathsFromDynamicRoute({
-    route,
-    filePath,
-    getStaticPaths
-  }) {
-    const staticPaths = await getStaticPaths({
-      appConfig: this.appConfig,
-      runtimeOrigin: this.origin
-    });
-    return staticPaths.paths.map((path2) => {
-      const dynamicParamsNames = this.getDynamicParamsNames(filePath);
-      let routeWithParams = route;
-      for (const param of dynamicParamsNames) {
-        routeWithParams = routeWithParams.replace(`[${param}]`, path2.params[param]);
-      }
-      return routeWithParams;
-    });
-  }
-  async createStaticRoutes({
-    filePath,
-    route,
-    routePath,
-    getStaticPaths
-  }) {
-    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}`);
-    }
-  }
-  async handleDynamicRouteCreation({ filePath, route, routePath }) {
-    const module = await this.importPageModule(filePath);
-    const Page = module.default;
-    const getStaticPaths = Page?.staticPaths ?? module.getStaticPaths;
-    const getStaticProps = Page?.staticProps ?? module.getStaticProps;
-    if (this.options.buildMode) {
-      invariant(getStaticProps !== void 0, `[ecopages] Missing getStaticProps in ${filePath}`);
-      invariant(getStaticPaths !== void 0, `[ecopages] Missing getStaticPaths in ${filePath}`);
-    }
-    if (getStaticPaths) {
-      return this.createStaticRoutes({
-        filePath,
-        route,
-        routePath,
-        getStaticPaths
-      });
-    }
-    return this.createRoute("dynamic", { filePath, route, routePath });
-  }
-  async importPageModule(filePath) {
-    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}`
-    });
-  }
-  createRoute(kind, { filePath, route, routePath }) {
-    this.routes[route] = {
-      kind,
-      pathname: routePath,
-      filePath
-    };
-  }
-  getRouteData(file) {
-    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 = isCatchAll ? "catch-all" : isDynamic ? "dynamic" : "exact";
-    return { route, routePath, filePath, kind };
-  }
-  async scan() {
-    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",
-              `\u27A4 ${routeData.filePath}`
-            );
-          }
-          this.createRoute(kind, routeData);
-          break;
-        default:
-          this.createRoute(kind, routeData);
-          break;
-      }
-    }
-    return this.routes;
-  }
-}
-export {
-  FSRouterScanner
-};