@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/router/modules/route-cache/domain/operations/cache-evict.ts

@@ -0,0 +1,104 @@
+import type { CacheState } from "../models";
+
+// 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/route-cache/domain/operations/cache-invalidate.ts

@@ -0,0 +1,101 @@
+import type { CacheEntry, CacheState } from "../models";
+
+// 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/route-cache/domain/operations/cache-read.ts

@@ -0,0 +1,74 @@
+import type { CacheMetadata, CacheState } from "../models";
+
+// 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/route-cache/domain/operations/cache-write.ts

@@ -0,0 +1,62 @@
+import type { CacheEntry, CacheMetadata, CacheState } from "../models";
+import { evictCache, updateAccess } from "./cache-evict";
+
+// 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/route-cache/domain/operations/index.ts

@@ -0,0 +1,4 @@
+export * from "./cache-evict";
+export * from "./cache-invalidate";
+export * from "./cache-read";
+export * from "./cache-write";

package/src/router/modules/route-cache/domain/validators/index.ts

@@ -0,0 +1,25 @@
+import type { CacheStrategy, EvictionPolicy } from "../models";
+
+export const validateCacheKey = (key: string): boolean => {
+	if (!key || typeof key !== "string") return false;
+	if (key.length === 0) return false;
+	return true;
+};
+
+export const validateTTL = (ttl: number): boolean => {
+	return typeof ttl === "number" && ttl > 0 && ttl <= Number.MAX_SAFE_INTEGER;
+};
+
+export const validateCacheStrategy = (strategy: CacheStrategy): boolean => {
+	return ["memory", "swr", "stale-while-revalidate", "server-side"].includes(
+		strategy,
+	);
+};
+
+export const validateEvictionPolicy = (policy: EvictionPolicy): boolean => {
+	return ["lru", "fifo", "lfu"].includes(policy);
+};
+
+export const validateCacheSize = (size: number): boolean => {
+	return typeof size === "number" && size > 0 && size <= 10000;
+};

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

@@ -0,0 +1,8 @@
+// Public API exports for route-cache 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-cache/ports/index.ts

@@ -0,0 +1,20 @@
+import type { CacheState } from "../types";
+
+// Port for cache storage (dependency injection point)
+export interface ICacheStorage {
+	get<T>(key: string): T | null;
+	set<T>(key: string, data: T, ttl?: number): void;
+	invalidate(key: string): void;
+	clear(): void;
+}
+
+// Port for cache persistence (dependency injection point)
+export interface ICachePersistence {
+	save(state: CacheState): Promise<void>;
+	load(): Promise<CacheState | null>;
+}
+
+// Port for cache warming (dependency injection point)
+export interface ICacheWarmer {
+	warmup(routes: string[]): Promise<void>;
+}

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

@@ -0,0 +1,8 @@
+export type {
+	CacheEntry,
+	CacheMetadata,
+	CacheState,
+	CacheStrategy,
+	EvictionPolicy,
+	ServerCacheConfig,
+} from "../domain/models";

package/src/router/modules/route-error-tracking/application/usecases/index.ts

@@ -0,0 +1,182 @@
+import {
+	createErrorTrackingState,
+	setMaxAggregations,
+	setMaxErrors,
+} from "../../domain";
+import {
+	clearAggregations,
+	clearAll,
+	clearErrors,
+	exportErrorsAsJSON,
+	generateErrorReport,
+	getAggregations,
+	getAggregationsByRoute,
+	getErrorRate,
+	getErrorStatistics,
+	getErrors,
+	getErrorsByType,
+	getErrorsInTimeRange,
+	getTopErrors,
+	recordError,
+} from "../../domain/operations";
+import type {
+	ErrorAggregation,
+	ErrorTrackingConfig,
+	ErrorTrackingState,
+	RouteError,
+} from "../../types";
+
+// Use case: Record error
+export const recordErrorUseCase = (
+	state: ErrorTrackingState,
+	route: string,
+	error: Error,
+	now: number,
+	userContext?: Record<string, unknown>,
+	metadata?: Record<string, unknown>,
+	userAgent?: string,
+): ErrorTrackingState => {
+	return recordError(
+		state,
+		route,
+		error,
+		now,
+		userContext,
+		metadata,
+		userAgent,
+	);
+};
+
+// Use case: Get errors
+export const getErrorsUseCase = (
+	state: ErrorTrackingState,
+	route?: string,
+): readonly RouteError[] => {
+	return getErrors(state, route);
+};
+
+// Use case: Get errors by type
+export const getErrorsByTypeUseCase = (
+	state: ErrorTrackingState,
+	errorType: string,
+): readonly RouteError[] => {
+	return getErrorsByType(state, errorType);
+};
+
+// Use case: Get errors in time range
+export const getErrorsInTimeRangeUseCase = (
+	state: ErrorTrackingState,
+	startTime: number,
+	endTime: number,
+): readonly RouteError[] => {
+	return getErrorsInTimeRange(state, startTime, endTime);
+};
+
+// Use case: Get aggregations
+export const getAggregationsUseCase = (
+	state: ErrorTrackingState,
+): readonly ErrorAggregation[] => {
+	return getAggregations(state);
+};
+
+// Use case: Get aggregations by route
+export const getAggregationsByRouteUseCase = (
+	state: ErrorTrackingState,
+	route: string,
+): readonly ErrorAggregation[] => {
+	return getAggregationsByRoute(state, route);
+};
+
+// Use case: Get top errors
+export const getTopErrorsUseCase = (
+	state: ErrorTrackingState,
+	limit = 10,
+): readonly ErrorAggregation[] => {
+	return getTopErrors(state, limit);
+};
+
+// Use case: Get error rate
+export const getErrorRateUseCase = (
+	state: ErrorTrackingState,
+	route: string,
+	now: number,
+	timeWindowMs = 60000,
+): number => {
+	return getErrorRate(state, route, now, timeWindowMs);
+};
+
+// Use case: Get error statistics
+export const getErrorStatisticsUseCase = (
+	state: ErrorTrackingState,
+	now: number,
+): {
+	readonly totalErrors: number;
+	readonly uniqueRoutes: number;
+	readonly uniqueErrorTypes: number;
+	readonly topError: string | null;
+	readonly errorRate: number;
+} => {
+	return getErrorStatistics(state, now);
+};
+
+// Use case: Clear errors
+export const clearErrorsUseCase = (
+	state: ErrorTrackingState,
+	route?: string,
+): ErrorTrackingState => {
+	return clearErrors(state, route);
+};
+
+// Use case: Clear aggregations
+export const clearAggregationsUseCase = (
+	state: ErrorTrackingState,
+	route?: string,
+): ErrorTrackingState => {
+	return clearAggregations(state, route);
+};
+
+// Use case: Clear all
+export const clearAllUseCase = (
+	state: ErrorTrackingState,
+): ErrorTrackingState => {
+	return clearAll(state);
+};
+
+// Use case: Set max errors
+export const setMaxErrorsUseCase = (
+	state: ErrorTrackingState,
+	max: number,
+): ErrorTrackingState => {
+	return setMaxErrors(state, max);
+};
+
+// Use case: Set max aggregations
+export const setMaxAggregationsUseCase = (
+	state: ErrorTrackingState,
+	max: number,
+): ErrorTrackingState => {
+	return setMaxAggregations(state, max);
+};
+
+// Use case: Generate error report
+export const generateErrorReportUseCase = (
+	state: ErrorTrackingState,
+	now: number,
+): string => {
+	return generateErrorReport(state, now);
+};
+
+// Use case: Export errors as JSON
+export const exportErrorsAsJSONUseCase = (
+	state: ErrorTrackingState,
+	now: number,
+): string => {
+	return exportErrorsAsJSON(state, now);
+};
+
+// Use case: Create error tracking state
+export const createErrorTrackingStateUseCase = (
+	config?: Partial<ErrorTrackingConfig>,
+): ErrorTrackingState => {
+	return createErrorTrackingState(config);
+};

package/src/router/modules/route-error-tracking/domain/index.ts

@@ -0,0 +1,5 @@
+// Domain layer exports
+
+export * from "./models";
+export * from "./operations";
+export * from "./validators";