@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/router/modules/route-testing/index.ts

@@ -0,0 +1,8 @@
+// Public API exports for route-testing module
+
+export * from "./application/usecases";
+export * from "./domain/models";
+export * from "./domain/operations";
+export * from "./domain/validators";
+export * from "./ports";
+export * from "./types";

package/src/router/modules/route-testing/ports/index.ts

@@ -0,0 +1,21 @@
+import type { E2ETest, E2ETestResult } from "../types";
+
+// Port for E2E test execution (dependency injection point)
+export interface IE2ETestExecutor {
+	runTest(test: E2ETest): Promise<E2ETestResult>;
+	runAllTests(tests: E2ETest[]): Promise<E2ETestResult[]>;
+}
+
+// Port for test reporting (dependency injection point)
+export interface ITestReporter {
+	generateReport(results: readonly E2ETestResult[]): string;
+	sendReport(report: string): Promise<void>;
+}
+
+// Port for test storage (dependency injection point)
+export interface ITestStorage {
+	saveTest(test: E2ETest): Promise<void>;
+	saveResult(result: E2ETestResult): Promise<void>;
+	getTests(): Promise<E2ETest[]>;
+	getResults(): Promise<E2ETestResult[]>;
+}

package/src/router/modules/route-testing/types/index.ts

@@ -0,0 +1,13 @@
+export type {
+	ContractTestResult,
+	ContractViolation,
+	E2ETest,
+	E2ETestingState,
+	E2ETestResult,
+	E2ETestStep,
+	LoaderSchema,
+	ParamSchema,
+	RouteContract,
+	TestingState,
+	TestRoute,
+} from "../domain/models";

package/src/router/modules/routing/application/index.ts

@@ -0,0 +1,7 @@
+export * from "./usecases";
+
+import { OptimizedRouteMatcher } from "../domain/optimized-matcher";
+
+export const createRouteMatcher = (routes: import("../types").RouteTree) => {
+	return new OptimizedRouteMatcher(routes);
+};

package/src/router/modules/routing/application/usecases.ts

@@ -0,0 +1,49 @@
+import type { Result } from "../../../shared/types";
+import { matchRoute } from "../domain";
+import type { MatchResult, RouteTree } from "../types";
+
+// Pure function to match a route
+export const matchRouteUseCase = (
+	routes: RouteTree,
+	path: string,
+): Result<MatchResult> => {
+	return matchRoute(routes, path);
+};
+
+// Pure function to add a route
+export const addRouteUseCase = (
+	routes: RouteTree,
+	route: RouteTree[number],
+): RouteTree => {
+	return [...routes, route];
+};
+
+// Pure function to remove a route
+export const removeRouteUseCase = (
+	routes: RouteTree,
+	path: string,
+): RouteTree => {
+	return routes.filter((r) => r.path !== path);
+};
+
+// Pure function to update a route
+export const updateRouteUseCase = (
+	routes: RouteTree,
+	path: string,
+	newRoute: RouteTree[number],
+): RouteTree => {
+	return routes.map((r) => (r.path === path ? newRoute : r));
+};
+
+// Pure function to get all routes
+export const getAllRoutesUseCase = (routes: RouteTree): RouteTree => {
+	return [...routes];
+};
+
+// Pure function to find a route by path
+export const findRouteUseCase = (
+	routes: RouteTree,
+	path: string,
+): RouteTree[number] | undefined => {
+	return routes.find((r) => r.path === path);
+};

package/src/router/modules/routing/domain/ab-testing.ts

@@ -0,0 +1,86 @@
+import type { RouteConfig } from "../../../shared/types";
+
+export type ABTestVariant = {
+	name: string;
+	weight: number; // 0-100
+	route: RouteConfig;
+};
+
+export type ABTest = {
+	name: string;
+	variants: ABTestVariant[];
+};
+
+export class ABTestManager {
+	private tests: Map<string, ABTest> = new Map();
+	private userAssignments: Map<string, Map<string, string>> = new Map();
+
+	addTest(test: ABTest): void {
+		this.tests.set(test.name, test);
+	}
+
+	getTest(name: string): ABTest | undefined {
+		return this.tests.get(name);
+	}
+
+	assignVariant(testName: string, userId: string, randomValue: number): string {
+		const test = this.tests.get(testName);
+		if (!test) return "";
+
+		const userTests = this.userAssignments.get(userId) || new Map();
+		const existing = userTests.get(testName);
+
+		if (existing) {
+			return existing;
+		}
+
+		// Assign variant based on weight
+		let cumulative = 0;
+		let assignedVariant = "";
+
+		for (const variant of test.variants) {
+			cumulative += variant.weight;
+			if (randomValue <= cumulative) {
+				assignedVariant = variant.name;
+				break;
+			}
+		}
+
+		userTests.set(testName, assignedVariant);
+		this.userAssignments.set(userId, userTests);
+
+		return assignedVariant;
+	}
+
+	getVariantRoute(
+		testName: string,
+		userId: string,
+		randomValue: number,
+	): RouteConfig | undefined {
+		const test = this.tests.get(testName);
+		if (!test) return undefined;
+
+		const variantName = this.assignVariant(testName, userId, randomValue);
+		const variant = test.variants.find((v) => v.name === variantName);
+
+		return variant?.route;
+	}
+
+	getAllTests(): ABTest[] {
+		return Array.from(this.tests.values());
+	}
+}
+
+export const createABTestManager = (): ABTestManager => {
+	return new ABTestManager();
+};
+
+export const createABTest = (
+	name: string,
+	variants: ABTestVariant[],
+): ABTest => {
+	return {
+		name,
+		variants,
+	};
+};

package/src/router/modules/routing/domain/analytics.ts

@@ -0,0 +1,88 @@
+export type RouteAnalytics = {
+	path: string;
+	views: number;
+	uniqueVisitors: Set<string>;
+	avgTimeOnPage: number;
+	bounceRate: number;
+};
+
+export class RouteAnalyticsManager {
+	private analytics: Map<string, RouteAnalytics> = new Map();
+	private visitorSessions: Map<string, Set<string>> = new Map();
+
+	recordView(path: string, visitorId: string): void {
+		const existing = this.analytics.get(path) || {
+			path,
+			views: 0,
+			uniqueVisitors: new Set(),
+			avgTimeOnPage: 0,
+			bounceRate: 0,
+		};
+
+		existing.views++;
+		existing.uniqueVisitors.add(visitorId);
+
+		this.analytics.set(path, existing);
+
+		// Track visitor session
+		const session = this.visitorSessions.get(visitorId) || new Set();
+		session.add(path);
+		this.visitorSessions.set(visitorId, session);
+	}
+
+	recordTimeOnPage(path: string, timeMs: number): void {
+		const existing = this.analytics.get(path);
+		if (existing) {
+			const totalTime = existing.avgTimeOnPage * existing.views + timeMs;
+			existing.avgTimeOnPage = totalTime / (existing.views + 1);
+		}
+	}
+
+	calculateBounceRate(path: string): number {
+		const analytics = this.analytics.get(path);
+		if (!analytics) return 0;
+
+		let bouncedVisitors = 0;
+		for (const [, paths] of this.visitorSessions) {
+			if (paths.size === 1 && paths.has(path)) {
+				bouncedVisitors++;
+			}
+		}
+
+		return (bouncedVisitors / analytics.uniqueVisitors.size) * 100;
+	}
+
+	getAnalytics(path: string): RouteAnalytics | undefined {
+		const analytics = this.analytics.get(path);
+		if (analytics) {
+			analytics.bounceRate = this.calculateBounceRate(path);
+		}
+		return analytics;
+	}
+
+	getAllAnalytics(): RouteAnalytics[] {
+		return Array.from(this.analytics.values()).map((a) => ({
+			...a,
+			bounceRate: this.calculateBounceRate(a.path),
+		}));
+	}
+
+	getPopularRoutes(limit: number = 10): RouteAnalytics[] {
+		return this.getAllAnalytics()
+			.sort((a, b) => b.views - a.views)
+			.slice(0, limit);
+	}
+
+	clearAnalytics(path: string): void {
+		this.analytics.delete(path);
+	}
+
+	clearAllAnalytics(): void {
+		this.analytics.clear();
+		this.visitorSessions.clear();
+	}
+}
+
+export const createRouteAnalyticsManager = (): RouteAnalyticsManager => {
+	return new RouteAnalyticsManager();
+};

package/src/router/modules/routing/domain/caching-evict.ts

@@ -0,0 +1,104 @@
+import type { CacheState } from "./caching-types";
+
+// Pure function to evict entries based on policy
+export const evictCache = (state: CacheState): CacheState => {
+	switch (state.serverConfig.evictionPolicy) {
+		case "lru":
+			return evictLRU(state);
+		case "fifo":
+			return evictFIFO(state);
+		case "lfu":
+			return evictLFU(state);
+		default:
+			return state;
+	}
+};
+
+// Pure function to evict LRU entry
+const evictLRU = (state: CacheState): CacheState => {
+	if (state.accessOrder.length === 0) return state;
+
+	const keyToRemove = state.accessOrder[0];
+	const newCache = { ...state.cache };
+	delete newCache[keyToRemove];
+
+	const newAccessCount = { ...state.accessCount };
+	delete newAccessCount[keyToRemove];
+
+	return {
+		...state,
+		cache: Object.freeze(newCache),
+		accessOrder: Object.freeze(state.accessOrder.slice(1)),
+		accessCount: Object.freeze(newAccessCount),
+	};
+};
+
+// Pure function to evict FIFO entry
+const evictFIFO = (state: CacheState): CacheState => {
+	const keys = Object.keys(state.cache);
+	if (keys.length === 0) return state;
+
+	const firstKey = keys[0];
+	const newCache = { ...state.cache };
+	delete newCache[firstKey];
+
+	const newAccessOrder = state.accessOrder.filter((k) => k !== firstKey);
+	const newAccessCount = Object.fromEntries(
+		Object.entries(state.accessCount).filter(([k]) => k !== firstKey),
+	);
+
+	return {
+		...state,
+		cache: Object.freeze(newCache),
+		accessOrder: Object.freeze(newAccessOrder),
+		accessCount: Object.freeze(newAccessCount),
+	};
+};
+
+// Pure function to evict LFU entry
+const evictLFU = (state: CacheState): CacheState => {
+	let minAccess = Infinity;
+	let keyToRemove: string | null = null;
+
+	for (const [key, count] of Object.entries(state.accessCount)) {
+		if (count < minAccess) {
+			minAccess = count;
+			keyToRemove = key;
+		}
+	}
+
+	if (!keyToRemove) return state;
+
+	const newCache = { ...state.cache };
+	delete newCache[keyToRemove];
+
+	const newAccessOrder = state.accessOrder.filter((k) => k !== keyToRemove);
+	const newAccessCount = Object.fromEntries(
+		Object.entries(state.accessCount).filter(([k]) => k !== keyToRemove),
+	);
+
+	return {
+		...state,
+		cache: Object.freeze(newCache),
+		accessOrder: Object.freeze(newAccessOrder),
+		accessCount: Object.freeze(newAccessCount),
+	};
+};
+
+// Pure function to update access tracking
+export const updateAccess = (state: CacheState, key: string): CacheState => {
+	// Update LRU order
+	const newAccessOrder = state.accessOrder.filter((k) => k !== key);
+
+	// Update LFU count
+	const currentCount = state.accessCount[key] || 0;
+
+	return {
+		...state,
+		accessOrder: Object.freeze([...newAccessOrder, key]),
+		accessCount: Object.freeze({
+			...state.accessCount,
+			[key]: currentCount + 1,
+		}),
+	};
+};

package/src/router/modules/routing/domain/caching-invalidate.ts

@@ -0,0 +1,101 @@
+import type { CacheEntry, CacheState } from "./caching-types";
+
+// Pure function to invalidate a cache entry
+export const invalidateCacheEntry = (
+	state: CacheState,
+	key: string,
+): CacheState => {
+	const newCache = { ...state.cache };
+	delete newCache[key];
+
+	return {
+		...state,
+		cache: Object.freeze(newCache),
+		accessOrder: state.accessOrder.filter((k) => k !== key),
+		accessCount: Object.freeze(
+			Object.fromEntries(
+				Object.entries(state.accessCount).filter(([k]) => k !== key),
+			),
+		),
+	};
+};
+
+// Pure function to invalidate cache entries by pattern
+export const invalidateCachePattern = (
+	state: CacheState,
+	pattern: string,
+): CacheState => {
+	const regex = new RegExp(pattern);
+	const newCache: Record<string, CacheEntry<unknown>> = {};
+	const newAccessOrder: string[] = [];
+	const newAccessCount: Record<string, number> = {};
+
+	for (const [key, entry] of Object.entries(state.cache)) {
+		if (!regex.test(key)) {
+			newCache[key] = entry;
+		}
+	}
+
+	for (const key of state.accessOrder) {
+		if (!regex.test(key)) {
+			newAccessOrder.push(key);
+		}
+	}
+
+	for (const [key, count] of Object.entries(state.accessCount)) {
+		if (!regex.test(key)) {
+			newAccessCount[key] = count;
+		}
+	}
+
+	return {
+		...state,
+		cache: Object.freeze(newCache),
+		accessOrder: Object.freeze(newAccessOrder),
+		accessCount: Object.freeze(newAccessCount),
+	};
+};
+
+// Pure function to clear all cache entries
+export const clearCache = (state: CacheState): CacheState => {
+	return {
+		...state,
+		cache: Object.freeze({}),
+		accessOrder: Object.freeze([]),
+		accessCount: Object.freeze({}),
+	};
+};
+
+// Pure function to invalidate by tag
+export const invalidateByTag = (state: CacheState, tag: string): CacheState => {
+	const newCache: Record<string, CacheEntry<unknown>> = {};
+	const newAccessOrder: string[] = [];
+	const newAccessCount: Record<string, number> = {};
+
+	for (const [key, entry] of Object.entries(state.cache)) {
+		if (!entry.metadata?.tags?.includes(tag)) {
+			newCache[key] = entry;
+		}
+	}
+
+	for (const key of state.accessOrder) {
+		const entry = state.cache[key];
+		if (entry && !entry.metadata?.tags?.includes(tag)) {
+			newAccessOrder.push(key);
+		}
+	}
+
+	for (const [key, count] of Object.entries(state.accessCount)) {
+		const entry = state.cache[key];
+		if (entry && !entry.metadata?.tags?.includes(tag)) {
+			newAccessCount[key] = count;
+		}
+	}
+
+	return {
+		...state,
+		cache: Object.freeze(newCache),
+		accessOrder: Object.freeze(newAccessOrder),
+		accessCount: Object.freeze(newAccessCount),
+	};
+};

package/src/router/modules/routing/domain/caching-read.ts

@@ -0,0 +1,74 @@
+import type { CacheMetadata, CacheState } from "./caching-types";
+
+// Pure function to get a cache entry
+export const getCacheEntry = <T>(
+	state: CacheState,
+	key: string,
+	now: number,
+): T | null => {
+	const entry = state.cache[key];
+
+	if (!entry) {
+		return null;
+	}
+
+	// Check if expired
+	if (entry.ttl && now - entry.timestamp > entry.ttl) {
+		if (state.strategy === "swr") {
+			// Return stale data but mark for revalidation
+			return entry.data as T;
+		}
+		return null;
+	}
+
+	return entry.data as T;
+};
+
+// Pure function to check if key exists
+export const hasCacheEntry = (state: CacheState, key: string): boolean => {
+	return key in state.cache;
+};
+
+// Pure function to get cache size
+export const getCacheSize = (state: CacheState): number => {
+	return Object.keys(state.cache).length;
+};
+
+// Pure function to get stale entries
+export const getStaleEntries = (state: CacheState, now: number): string[] => {
+	const stale: string[] = [];
+
+	for (const [key, entry] of Object.entries(state.cache)) {
+		if (entry.ttl && now - entry.timestamp > entry.ttl) {
+			stale.push(key);
+		}
+	}
+
+	return stale;
+};
+
+// Pure function to get metadata
+export const getCacheMetadata = (
+	state: CacheState,
+	key: string,
+): CacheMetadata | undefined => {
+	return state.cache[key]?.metadata;
+};
+
+// Pure function to get cache stats
+export const getCacheStats = (
+	state: CacheState,
+	now: number,
+): {
+	size: number;
+	maxSize: number;
+	hitRate: number;
+	staleCount: number;
+} => {
+	return {
+		size: Object.keys(state.cache).length,
+		maxSize: state.serverConfig.maxSize,
+		hitRate: 0,
+		staleCount: getStaleEntries(state, now).length,
+	};
+};

package/src/router/modules/routing/domain/caching-state.ts

@@ -0,0 +1,38 @@
+import type {
+	CacheState,
+	CacheStrategy,
+	ServerCacheConfig,
+} from "./caching-types";
+
+// Pure function to create initial cache state
+export const createCacheState = (
+	strategy: CacheStrategy = "swr",
+	serverConfig?: Partial<ServerCacheConfig>,
+): CacheState => {
+	const defaultServerConfig: ServerCacheConfig = {
+		maxSize: 1000,
+		evictionPolicy: "lru",
+		persistenceEnabled: false,
+		warmupEnabled: false,
+		warmupRoutes: [],
+	};
+
+	return Object.freeze({
+		cache: Object.freeze({}),
+		strategy,
+		defaultTTL: 60000,
+		serverConfig: serverConfig
+			? { ...defaultServerConfig, ...serverConfig }
+			: defaultServerConfig,
+		accessOrder: Object.freeze([]),
+		accessCount: Object.freeze({}),
+	});
+};
+
+// Pure function to create route cache manager
+export const createRouteCacheManager = (
+	strategy?: CacheStrategy,
+	serverConfig?: Partial<ServerCacheConfig>,
+): CacheState => {
+	return createCacheState(strategy, serverConfig);
+};

package/src/router/modules/routing/domain/caching-types.ts

@@ -0,0 +1,38 @@
+export type CacheEntry<T> = {
+	readonly data: T;
+	readonly timestamp: number;
+	readonly ttl?: number;
+	readonly metadata?: CacheMetadata;
+};
+
+export interface CacheMetadata {
+	readonly size: number;
+	readonly tags: readonly string[];
+	readonly etag?: string;
+	readonly lastModified?: number;
+}
+
+export type CacheStrategy =
+	| "memory"
+	| "swr"
+	| "stale-while-revalidate"
+	| "server-side";
+export type EvictionPolicy = "lru" | "fifo" | "lfu";
+
+export interface ServerCacheConfig {
+	readonly maxSize: number;
+	readonly evictionPolicy: EvictionPolicy;
+	readonly persistenceEnabled: boolean;
+	readonly persistencePath?: string;
+	readonly warmupEnabled: boolean;
+	readonly warmupRoutes: readonly string[];
+}
+
+export type CacheState = {
+	readonly cache: Readonly<Record<string, CacheEntry<unknown>>>;
+	readonly strategy: CacheStrategy;
+	readonly defaultTTL: number;
+	readonly serverConfig: ServerCacheConfig;
+	readonly accessOrder: readonly string[];
+	readonly accessCount: Readonly<Record<string, number>>;
+};

package/src/router/modules/routing/domain/caching-write.ts

@@ -0,0 +1,62 @@
+import { evictCache, updateAccess } from "./caching-evict";
+import type { CacheEntry, CacheMetadata, CacheState } from "./caching-types";
+
+// Pure function to set a cache entry
+export const setCacheEntry = <T>(
+	state: CacheState,
+	key: string,
+	data: T,
+	now: number,
+	ttl?: number,
+	metadata?: CacheMetadata,
+): CacheState => {
+	let newCache = { ...state.cache };
+
+	// Check if we need to evict entries
+	if (Object.keys(newCache).length >= state.serverConfig.maxSize) {
+		const evictedState = evictCache(state);
+		newCache = evictedState.cache;
+	}
+
+	const entry: CacheEntry<T> = {
+		data,
+		timestamp: now,
+		ttl: ttl || state.defaultTTL,
+		...(metadata !== undefined && { metadata }),
+	};
+
+	newCache = { ...newCache, [key]: entry };
+
+	// Update access tracking
+	const updatedState = updateAccess(state, key);
+
+	return {
+		...updatedState,
+		cache: Object.freeze(newCache),
+	};
+};
+
+// Pure function to warmup routes
+export const warmupRoutes = (
+	state: CacheState,
+	routes: string[],
+	now: number,
+): CacheState => {
+	let newState = state;
+
+	for (const route of routes) {
+		newState = setCacheEntry(
+			newState,
+			route,
+			{ warmed: true },
+			now,
+			state.defaultTTL,
+			{
+				size: 0,
+				tags: ["warmup"],
+			},
+		);
+	}
+
+	return newState;
+};

package/src/router/modules/routing/domain/caching.ts

@@ -0,0 +1,6 @@
+export * from "./caching-evict";
+export * from "./caching-invalidate";
+export * from "./caching-read";
+export * from "./caching-state";
+export * from "./caching-types";
+export * from "./caching-write";