@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.27

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/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,
+	};
+}

package/src/services/validation/schema-validation-service.test.ts

@@ -0,0 +1,223 @@
+import { describe, test, expect } from 'vitest';
+import { z } from 'zod';
+import * as v from 'valibot';
+import { type } from 'arktype';
+import { SchemaValidationService } from './schema-validation-service.ts';
+
+describe('SchemaValidationService', () => {
+	const service = new SchemaValidationService();
+
+	describe('Zod validation', () => {
+		test('validates body with Zod schema', async () => {
+			const schema = z.object({
+				title: z.string().min(1),
+				count: z.number(),
+			});
+
+			const result = await service.validateRequest(
+				{ body: { title: 'Hello', count: 42 } },
+				{ body: schema as unknown as Parameters<typeof service.validateRequest>[1]['body'] },
+			);
+
+			expect(result.success).toBe(true);
+			expect(result.data?.body).toEqual({ title: 'Hello', count: 42 });
+		});
+
+		test('rejects invalid body with Zod schema', async () => {
+			const schema = z.object({
+				title: z.string().min(1),
+				count: z.number(),
+			});
+
+			const result = await service.validateRequest(
+				{ body: { title: '', count: 'not-a-number' } },
+				{ body: schema as unknown as Parameters<typeof service.validateRequest>[1]['body'] },
+			);
+
+			expect(result.success).toBe(false);
+			expect(result.errors).toBeDefined();
+			expect(result.errors!.length).toBeGreaterThan(0);
+		});
+	});
+
+	describe('Valibot validation', () => {
+		test('validates query with Valibot schema', async () => {
+			const schema = v.object({
+				page: v.string(),
+				limit: v.string(),
+			});
+
+			const result = await service.validateRequest(
+				{ query: { page: '1', limit: '10' } },
+				{ query: schema as unknown as Parameters<typeof service.validateRequest>[1]['query'] },
+			);
+
+			expect(result.success).toBe(true);
+			expect(result.data?.query).toEqual({ page: '1', limit: '10' });
+		});
+
+		test('rejects invalid query with Valibot schema', async () => {
+			const schema = v.object({
+				page: v.pipe(v.string(), v.minLength(1)),
+			});
+
+			const result = await service.validateRequest(
+				{ query: { page: '' } },
+				{ query: schema as unknown as Parameters<typeof service.validateRequest>[1]['query'] },
+			);
+
+			expect(result.success).toBe(false);
+			expect(result.errors).toBeDefined();
+		});
+	});
+
+	describe('ArkType validation', () => {
+		test('validates headers with ArkType schema', async () => {
+			const schema = type({
+				'content-type': 'string',
+				authorization: 'string',
+			});
+
+			const result = await service.validateRequest(
+				{
+					headers: {
+						'content-type': 'application/json',
+						authorization: 'Bearer token',
+					},
+				},
+				{ headers: schema as unknown as Parameters<typeof service.validateRequest>[1]['headers'] },
+			);
+
+			expect(result.success).toBe(true);
+			expect(result.data?.headers).toEqual({
+				'content-type': 'application/json',
+				authorization: 'Bearer token',
+			});
+		});
+
+		test('rejects invalid headers with ArkType schema', async () => {
+			const schema = type({
+				'content-type': 'string',
+				'x-custom': 'string>5',
+			});
+
+			const result = await service.validateRequest(
+				{
+					headers: {
+						'content-type': 'application/json',
+						'x-custom': 'ab',
+					},
+				},
+				{ headers: schema as unknown as Parameters<typeof service.validateRequest>[1]['headers'] },
+			);
+
+			expect(result.success).toBe(false);
+			expect(result.errors).toBeDefined();
+		});
+	});
+
+	describe('Combined validation', () => {
+		test('validates multiple sources at once', async () => {
+			const bodySchema = z.object({
+				title: z.string(),
+			});
+			const querySchema = v.object({
+				format: v.string(),
+			});
+
+			const result = await service.validateRequest(
+				{
+					body: { title: 'Post Title' },
+					query: { format: 'json' },
+				},
+				{
+					body: bodySchema as unknown as Parameters<typeof service.validateRequest>[1]['body'],
+					query: querySchema as unknown as Parameters<typeof service.validateRequest>[1]['query'],
+				},
+			);
+
+			expect(result.success).toBe(true);
+			expect(result.data?.body).toEqual({ title: 'Post Title' });
+			expect(result.data?.query).toEqual({ format: 'json' });
+		});
+
+		test('validates route params with schema', async () => {
+			const paramsSchema = z.object({
+				id: z.coerce.number().int(),
+			});
+
+			const result = await service.validateRequest(
+				{
+					params: { id: '42' },
+				},
+				{
+					params: paramsSchema as unknown as Parameters<typeof service.validateRequest>[1]['params'],
+				},
+			);
+
+			expect(result.success).toBe(true);
+			expect(result.data?.params).toEqual({ id: 42 });
+		});
+
+		test('aggregates errors from multiple sources', async () => {
+			const bodySchema = z.object({
+				title: z.string().min(5),
+			});
+			const querySchema = v.object({
+				page: v.pipe(v.string(), v.regex(/^\d+$/)),
+			});
+
+			const result = await service.validateRequest(
+				{
+					body: { title: 'ab' },
+					query: { page: 'invalid' },
+				},
+				{
+					body: bodySchema as unknown as Parameters<typeof service.validateRequest>[1]['body'],
+					query: querySchema as unknown as Parameters<typeof service.validateRequest>[1]['query'],
+				},
+			);
+
+			expect(result.success).toBe(false);
+			expect(result.errors).toBeDefined();
+			expect(result.errors!.length).toBeGreaterThan(1);
+		});
+	});
+
+	describe('Edge cases', () => {
+		test('handles missing optional schemas', async () => {
+			const result = await service.validateRequest({ body: { data: 'test' } }, {});
+
+			expect(result.success).toBe(true);
+			expect(result.data).toEqual({});
+		});
+
+		test('handles undefined source data', async () => {
+			const schema = z.object({ name: z.string() });
+
+			const result = await service.validateRequest(
+				{ body: undefined },
+				{ body: schema as unknown as Parameters<typeof service.validateRequest>[1]['body'] },
+			);
+
+			expect(result.success).toBe(true);
+		});
+
+		test('catches validation exceptions', async () => {
+			const brokenSchema = {
+				'~standard': {
+					version: 1,
+					vendor: 'test',
+					validate: () => {
+						throw new Error('Validation crashed');
+					},
+				},
+			} as const;
+
+			const result = await service.validateRequest({ body: { test: true } }, { body: brokenSchema });
+
+			expect(result.success).toBe(false);
+			expect(result.errors?.[0]?.message).toBe('Validation crashed');
+		});
+	});
+});