@ecopages/core 0.2.0-alpha.22 → 0.2.0-alpha.24

package/src/services/runtime-state/dev-graph.service.ts

@@ -0,0 +1,217 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import {
+	CounterServerInvalidationState,
+	getAppServerInvalidationState,
+	setAppServerInvalidationState,
+	type ServerInvalidationState,
+} from './server-invalidation-state.service.ts';
+import {
+	getAppEntrypointDependencyGraph,
+	InMemoryEntrypointDependencyGraph,
+	NoopEntrypointDependencyGraph,
+	setAppEntrypointDependencyGraph,
+	type EntrypointDependencyGraph,
+} from './entrypoint-dependency-graph.service.ts';
+
+/**
+ * Tracks development-time dependency relationships and invalidation state for
+ * one Ecopages app instance.
+ *
+ * @remarks
+ * The current contract stays intentionally small. It supports today's needs for
+ * server-module cache invalidation and entrypoint-to-dependency lookups without
+ * forcing the rest of the runtime to know about one specific graph
+ * implementation.
+ */
+export interface DevGraphService extends ServerInvalidationState, EntrypointDependencyGraph {}
+
+/**
+ * Minimal dev-graph implementation used when an app has no selective graph
+ * metadata available.
+ *
+ * @remarks
+ * This preserves correct behavior by using coarse invalidation version bumps.
+ * Callers still pass changed-file information through the interface now so a
+ * richer graph can become more selective later without changing call sites.
+ */
+export class NoopDevGraphService implements DevGraphService {
+	private readonly invalidationState = new CounterServerInvalidationState();
+	private readonly dependencyGraph = new NoopEntrypointDependencyGraph();
+
+	/**
+	 * Returns the current coarse invalidation version.
+	 */
+	getServerInvalidationVersion(): number {
+		return this.invalidationState.getServerInvalidationVersion();
+	}
+
+	/**
+	 * Invalidates all server-side module state by incrementing the shared version.
+	 */
+	invalidateServerModules(changedFiles?: string[]): void {
+		this.invalidationState.invalidateServerModules(changedFiles);
+	}
+
+	/**
+	 * Indicates that this graph cannot target invalidation to one entrypoint set.
+	 */
+	supportsSelectiveInvalidation(): boolean {
+		return this.dependencyGraph.supportsSelectiveInvalidation();
+	}
+
+	/**
+	 * Returns an empty entrypoint set because this implementation stores no
+	 * dependency graph metadata.
+	 */
+	getDependencyEntrypoints(filePath: string): Set<string> {
+		return this.dependencyGraph.getDependencyEntrypoints(filePath);
+	}
+
+	/**
+	 * Accepts dependency updates to preserve interface compatibility, but stores no
+	 * graph state in the noop implementation.
+	 */
+	setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void {
+		this.dependencyGraph.setEntrypointDependencies(entrypointPath, dependencies);
+	}
+
+	/**
+	 * Clears one entrypoint from the graph.
+	 *
+	 * @remarks
+	 * There is no stored graph state in this implementation, so this is a no-op.
+	 */
+	clearEntrypointDependencies(entrypointPath: string): void {
+		this.dependencyGraph.clearEntrypointDependencies(entrypointPath);
+	}
+
+	/**
+	 * Resets graph-owned state for a fresh runtime cycle.
+	 */
+	reset(): void {
+		this.invalidationState.reset();
+		this.dependencyGraph.reset();
+	}
+}
+
+/**
+ * In-memory development graph with entrypoint-to-dependency reverse lookups.
+ *
+ * @remarks
+ * This is the current selective graph implementation used by development flows
+ * that need to answer which entrypoints depend on a changed file while still
+ * keeping invalidation state app-local.
+ */
+export class InMemoryDevGraphService implements DevGraphService {
+	private readonly invalidationState = new CounterServerInvalidationState();
+	private readonly dependencyGraph = new InMemoryEntrypointDependencyGraph();
+
+	/**
+	 * Returns the current app-local server invalidation version.
+	 */
+	getServerInvalidationVersion(): number {
+		return this.invalidationState.getServerInvalidationVersion();
+	}
+
+	/**
+	 * Invalidates the current server-module cache generation.
+	 *
+	 * @remarks
+	 * The current implementation still uses a coarse generation bump for server
+	 * modules. Selective dependency lookups are used by callers that need to limit
+	 * browser rebuild work.
+	 */
+	invalidateServerModules(changedFiles?: string[]): void {
+		this.invalidationState.invalidateServerModules(changedFiles);
+	}
+
+	/**
+	 * Indicates that this graph can answer dependency-to-entrypoint lookups.
+	 */
+	supportsSelectiveInvalidation(): boolean {
+		return this.dependencyGraph.supportsSelectiveInvalidation();
+	}
+
+	/**
+	 * Returns all known entrypoints that currently depend on the given file.
+	 */
+	getDependencyEntrypoints(filePath: string): Set<string> {
+		return this.dependencyGraph.getDependencyEntrypoints(filePath);
+	}
+
+	/**
+	 * Replaces the stored dependency set for one entrypoint.
+	 *
+	 * @remarks
+	 * The entrypoint itself is always included in its own dependency set so reverse
+	 * lookups can map a changed entry file back to that same entrypoint.
+	 */
+	setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void {
+		this.dependencyGraph.setEntrypointDependencies(entrypointPath, dependencies);
+	}
+
+	/**
+	 * Removes one entrypoint and all of its reverse dependency edges.
+	 */
+	clearEntrypointDependencies(entrypointPath: string): void {
+		this.dependencyGraph.clearEntrypointDependencies(entrypointPath);
+	}
+
+	/**
+	 * Clears all graph state and starts a fresh invalidation generation.
+	 */
+	reset(): void {
+		this.invalidationState.reset();
+		this.dependencyGraph.reset();
+	}
+}
+
+/**
+ * Returns the dev-graph service owned by one app instance.
+ */
+export function getAppDevGraphService(appConfig: EcoPagesAppConfig): DevGraphService {
+	if (appConfig.runtime?.devGraphService) {
+		return appConfig.runtime.devGraphService;
+	}
+
+	const serverInvalidationState = getAppServerInvalidationState(appConfig);
+	const entrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
+
+	return {
+		getServerInvalidationVersion: () => serverInvalidationState.getServerInvalidationVersion(),
+		invalidateServerModules: (changedFiles) => serverInvalidationState.invalidateServerModules(changedFiles),
+		supportsSelectiveInvalidation: () => entrypointDependencyGraph.supportsSelectiveInvalidation(),
+		getDependencyEntrypoints: (filePath) => entrypointDependencyGraph.getDependencyEntrypoints(filePath),
+		setEntrypointDependencies: (entrypointPath, dependencies) =>
+			entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, dependencies),
+		clearEntrypointDependencies: (entrypointPath) =>
+			entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath),
+		reset: () => {
+			serverInvalidationState.reset();
+			entrypointDependencyGraph.reset();
+		},
+	};
+}
+
+/**
+ * Installs the dev-graph service that should back one app/runtime instance.
+ */
+export function setAppDevGraphService(appConfig: EcoPagesAppConfig, devGraphService: DevGraphService): void {
+	setAppServerInvalidationState(appConfig, {
+		getServerInvalidationVersion: () => devGraphService.getServerInvalidationVersion(),
+		invalidateServerModules: (changedFiles) => devGraphService.invalidateServerModules(changedFiles),
+		reset: () => devGraphService.reset(),
+	});
+	setAppEntrypointDependencyGraph(appConfig, {
+		supportsSelectiveInvalidation: () => devGraphService.supportsSelectiveInvalidation(),
+		getDependencyEntrypoints: (filePath) => devGraphService.getDependencyEntrypoints(filePath),
+		setEntrypointDependencies: (entrypointPath, dependencies) =>
+			devGraphService.setEntrypointDependencies(entrypointPath, dependencies),
+		clearEntrypointDependencies: (entrypointPath) => devGraphService.clearEntrypointDependencies(entrypointPath),
+		reset: () => devGraphService.reset(),
+	});
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		devGraphService,
+	};
+}

package/src/services/runtime-state/entrypoint-dependency-graph.service.ts

@@ -0,0 +1,136 @@
+import path from 'node:path';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type { DevGraphService } from './dev-graph.service.ts';
+
+/**
+ * App-owned dependency graph used to target browser entrypoint rebuilds.
+ */
+export interface EntrypointDependencyGraph {
+	supportsSelectiveInvalidation(): boolean;
+	getDependencyEntrypoints(filePath: string): Set<string>;
+	setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void;
+	clearEntrypointDependencies(entrypointPath: string): void;
+	reset(): void;
+}
+
+/**
+ * Graph implementation for runtimes that rebuild every watched entrypoint.
+ */
+export class NoopEntrypointDependencyGraph implements EntrypointDependencyGraph {
+	supportsSelectiveInvalidation(): boolean {
+		return false;
+	}
+
+	getDependencyEntrypoints(_filePath: string): Set<string> {
+		return new Set();
+	}
+
+	setEntrypointDependencies(_entrypointPath: string, _dependencies: string[]): void {}
+
+	clearEntrypointDependencies(_entrypointPath: string): void {}
+
+	reset(): void {}
+}
+
+/**
+ * In-memory entrypoint-to-dependency graph with reverse dependency lookups.
+ */
+export class InMemoryEntrypointDependencyGraph implements EntrypointDependencyGraph {
+	private readonly dependencyEntrypoints = new Map<string, Set<string>>();
+	private readonly entrypointDependencies = new Map<string, Set<string>>();
+
+	supportsSelectiveInvalidation(): boolean {
+		return true;
+	}
+
+	getDependencyEntrypoints(filePath: string): Set<string> {
+		return new Set(this.dependencyEntrypoints.get(path.resolve(filePath)) ?? []);
+	}
+
+	setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void {
+		const normalizedEntrypoint = path.resolve(entrypointPath);
+
+		this.clearEntrypointDependencies(normalizedEntrypoint);
+
+		const normalizedDependencies = new Set<string>([
+			normalizedEntrypoint,
+			...dependencies.map((dependencyPath) => path.resolve(dependencyPath)),
+		]);
+
+		this.entrypointDependencies.set(normalizedEntrypoint, normalizedDependencies);
+
+		for (const dependencyPath of normalizedDependencies) {
+			const entrypoints = this.dependencyEntrypoints.get(dependencyPath) ?? new Set<string>();
+			entrypoints.add(normalizedEntrypoint);
+			this.dependencyEntrypoints.set(dependencyPath, entrypoints);
+		}
+	}
+
+	clearEntrypointDependencies(entrypointPath: string): void {
+		const normalizedEntrypoint = path.resolve(entrypointPath);
+		const previousDependencies = this.entrypointDependencies.get(normalizedEntrypoint);
+
+		if (!previousDependencies) {
+			return;
+		}
+
+		for (const dependencyPath of previousDependencies) {
+			const entrypoints = this.dependencyEntrypoints.get(dependencyPath);
+			if (!entrypoints) {
+				continue;
+			}
+
+			entrypoints.delete(normalizedEntrypoint);
+			if (entrypoints.size === 0) {
+				this.dependencyEntrypoints.delete(dependencyPath);
+			}
+		}
+
+		this.entrypointDependencies.delete(normalizedEntrypoint);
+	}
+
+	reset(): void {
+		this.dependencyEntrypoints.clear();
+		this.entrypointDependencies.clear();
+	}
+}
+
+function isLegacyEntrypointDependencyGraph(value: unknown): value is DevGraphService {
+	return (
+		Boolean(value) &&
+		typeof value === 'object' &&
+		typeof (value as EntrypointDependencyGraph).supportsSelectiveInvalidation === 'function' &&
+		typeof (value as EntrypointDependencyGraph).getDependencyEntrypoints === 'function' &&
+		typeof (value as EntrypointDependencyGraph).setEntrypointDependencies === 'function' &&
+		typeof (value as EntrypointDependencyGraph).clearEntrypointDependencies === 'function' &&
+		typeof (value as EntrypointDependencyGraph).reset === 'function'
+	);
+}
+
+/**
+ * Returns the app-owned entrypoint dependency graph.
+ */
+export function getAppEntrypointDependencyGraph(appConfig: EcoPagesAppConfig): EntrypointDependencyGraph {
+	if (appConfig.runtime?.entrypointDependencyGraph) {
+		return appConfig.runtime.entrypointDependencyGraph;
+	}
+
+	if (isLegacyEntrypointDependencyGraph(appConfig.runtime?.devGraphService)) {
+		return appConfig.runtime.devGraphService;
+	}
+
+	return new NoopEntrypointDependencyGraph();
+}
+
+/**
+ * Installs the dependency graph used by one app instance.
+ */
+export function setAppEntrypointDependencyGraph(
+	appConfig: EcoPagesAppConfig,
+	entrypointDependencyGraph: EntrypointDependencyGraph,
+): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		entrypointDependencyGraph,
+	};
+}

package/src/services/runtime-state/runtime-specifier-registry.service.ts

@@ -0,0 +1,96 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+
+/**
+ * Stores runtime-visible bare-specifier mappings for one app instance.
+ *
+ * @remarks
+ * Integrations populate this registry during runtime setup when they expose
+ * browser runtime modules through stable bare imports. Build and HMR code later
+ * consume the collected map to create aliasing and bootstrap behavior without
+ * forcing integrations to own global registry state.
+ */
+export interface RuntimeSpecifierRegistry {
+	/**
+	 * Merges a new batch of specifier mappings into the registry.
+	 *
+	 * @remarks
+	 * Later registrations replace earlier URLs for the same specifier. This keeps
+	 * runtime setup deterministic while still allowing an integration to refresh
+	 * its own declarations during one app session.
+	 */
+	register(map: Record<string, string>): void;
+
+	/**
+	 * Returns the current registry contents.
+	 *
+	 * @remarks
+	 * The returned map is the live backing map for the registry implementation, so
+	 * callers should treat it as read-only unless they intentionally own registry
+	 * mutation semantics.
+	 */
+	getAll(): Map<string, string>;
+
+	/**
+	 * Removes all registered specifiers for the current app/runtime instance.
+	 */
+	clear(): void;
+}
+
+/**
+ * Default in-memory runtime specifier registry used by core.
+ *
+ * @remarks
+ * Runtime specifier maps are app-local bootstrap metadata, not durable build
+ * artifacts, so the default implementation stays intentionally small.
+ */
+export class InMemoryRuntimeSpecifierRegistry implements RuntimeSpecifierRegistry {
+	private readonly specifierMap = new Map<string, string>();
+
+	/**
+	 * Merges one integration-provided mapping set into the app registry.
+	 */
+	register(map: Record<string, string>): void {
+		for (const [specifier, url] of Object.entries(map)) {
+			this.specifierMap.set(specifier, url);
+		}
+	}
+
+	/**
+	 * Returns the live app-owned mapping table.
+	 */
+	getAll(): Map<string, string> {
+		return this.specifierMap;
+	}
+
+	/**
+	 * Clears all mappings for the current runtime session.
+	 */
+	clear(): void {
+		this.specifierMap.clear();
+	}
+}
+
+/**
+ * Returns the runtime specifier registry owned by one app instance.
+ *
+ * @remarks
+ * Older tests and helpers may not seed runtime state explicitly yet, so this
+ * helper still provides an in-memory fallback when the app runtime has not been
+ * initialized.
+ */
+export function getAppRuntimeSpecifierRegistry(appConfig: EcoPagesAppConfig): RuntimeSpecifierRegistry {
+	return appConfig.runtime?.runtimeSpecifierRegistry ?? new InMemoryRuntimeSpecifierRegistry();
+}
+
+/**
+ * Installs the runtime specifier registry that should back one app instance.
+ */
+export function setAppRuntimeSpecifierRegistry(
+	appConfig: EcoPagesAppConfig,
+	runtimeSpecifierRegistry: RuntimeSpecifierRegistry,
+): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		runtimeSpecifierRegistry,
+	};
+}

package/src/services/runtime-state/server-invalidation-state.service.ts

@@ -0,0 +1,68 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type { DevGraphService } from './dev-graph.service.ts';
+
+/**
+ * App-owned coarse invalidation state for server-executed modules.
+ */
+export interface ServerInvalidationState {
+	getServerInvalidationVersion(): number;
+	invalidateServerModules(changedFiles?: string[]): void;
+	reset(): void;
+}
+
+/**
+ * Minimal app-local invalidation state backed by a single generation counter.
+ */
+export class CounterServerInvalidationState implements ServerInvalidationState {
+	private serverInvalidationVersion = 0;
+
+	getServerInvalidationVersion(): number {
+		return this.serverInvalidationVersion;
+	}
+
+	invalidateServerModules(_changedFiles?: string[]): void {
+		this.serverInvalidationVersion += 1;
+	}
+
+	reset(): void {
+		this.serverInvalidationVersion += 1;
+	}
+}
+
+function isLegacyServerInvalidationState(value: unknown): value is DevGraphService {
+	return (
+		Boolean(value) &&
+		typeof value === 'object' &&
+		typeof (value as ServerInvalidationState).getServerInvalidationVersion === 'function' &&
+		typeof (value as ServerInvalidationState).invalidateServerModules === 'function' &&
+		typeof (value as ServerInvalidationState).reset === 'function'
+	);
+}
+
+/**
+ * Returns the app-owned server invalidation state.
+ */
+export function getAppServerInvalidationState(appConfig: EcoPagesAppConfig): ServerInvalidationState {
+	if (appConfig.runtime?.serverInvalidationState) {
+		return appConfig.runtime.serverInvalidationState;
+	}
+
+	if (isLegacyServerInvalidationState(appConfig.runtime?.devGraphService)) {
+		return appConfig.runtime.devGraphService;
+	}
+
+	return new CounterServerInvalidationState();
+}
+
+/**
+ * Installs the invalidation state used by one app instance.
+ */
+export function setAppServerInvalidationState(
+	appConfig: EcoPagesAppConfig,
+	serverInvalidationState: ServerInvalidationState,
+): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		serverInvalidationState,
+	};
+}