@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/router/modules/routing/domain/interactive-docs-advanced-sections.ts

@@ -0,0 +1,164 @@
+import type { DocumentationSection } from "./interactive-docs";
+
+export const advancedDocumentationSections: readonly DocumentationSection[] = [
+	{
+		id: "performance",
+		title: "Performance Monitoring",
+		content: "Monitor and optimize route performance.",
+		examples: [
+			{
+				code: `import { createRoutePerformanceMonitor } from '@wrikka/solid-framework/router';
+	
+	const monitor = createRoutePerformanceMonitor();
+	
+	monitor.startLoad('/users');
+	// ... load route
+	monitor.endLoad('/users');
+	
+	const metrics = monitor.getMetrics('/users');
+	console.log(metrics.loadTime);`,
+				description: "Monitoring route performance",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["caching", "preloading"],
+	},
+	{
+		id: "preloading",
+		title: "Predictive Preloading",
+		content: "Preload routes based on user behavior patterns.",
+		examples: [
+			{
+				code: `import { createPredictiveRoutePreloader } from '@wrikka/solid-framework/router';
+	
+	const preloader = createPredictiveRoutePreloader(routes);
+	
+	preloader.recordNavigation('/home');
+	preloader.recordNavigation('/users');
+	
+	const predictions = preloader.getTopPredictions(3);
+	predictions.forEach(p => {
+	  preloadRoute(p.route);
+	});`,
+				description: "Predictive route preloading",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["caching", "performance"],
+	},
+	{
+		id: "security",
+		title: "Security",
+		content:
+			"Scan routes for security vulnerabilities and implement best practices.",
+		examples: [
+			{
+				code: `import { createSecurityScanner } from '@wrikka/solid-framework/router';
+	
+	const scanner = createSecurityScanner();
+	
+	const issues = scanner.scanRoutes(routes);
+	const report = scanner.generateReport();
+	
+	console.log(report.securityScore);`,
+				description: "Security scanning",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["guards", "rbac"],
+	},
+	{
+		id: "e2e",
+		title: "E2E Testing",
+		content: "Create end-to-end tests for your routes.",
+		examples: [
+			{
+				code: `import { createE2ERouteTester } from '@wrikka/solid-framework/router';
+	
+	const tester = createE2ERouteTester();
+	
+	const test = tester.createE2ETest(
+	  'User Flow',
+	  '/users',
+	  [
+	    { action: 'navigate', value: '/users' },
+	    { action: 'wait', timeout: 1000 },
+	    { action: 'assert', assertion: 'Page loaded' },
+	  ],
+	);
+	
+	const result = await tester.runTest(test);`,
+				description: "E2E test setup",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["testing", "navigation"],
+	},
+	{
+		id: "links",
+		title: "Type-Safe Links",
+		content: "Create type-safe navigation links with autocomplete.",
+		examples: [
+			{
+				code: `import { createRouteAutocomplete } from '@wrikka/solid-framework/router';
+	
+	const autocomplete = createRouteAutocomplete(routes);
+	
+	const suggestions = autocomplete.getSuggestions({
+	  currentPath: '/use',
+	  cursorPosition: 4,
+	  routes,
+	});`,
+				description: "Route autocomplete",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["navigation", "routing"],
+	},
+	{
+		id: "middleware",
+		title: "Middleware",
+		content: "Add middleware for route processing and transformations.",
+		examples: [
+			{
+				code: `const loggingMiddleware = (context, next) => {
+	  console.log(\`Navigating to \${context.to}\`);
+	  return next();
+	};
+	
+	const routes = [
+	  {
+	    path: '/api/*',
+	    middleware: [loggingMiddleware],
+	  },
+	];`,
+				description: "Route middleware",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["guards", "i18n"],
+	},
+	{
+		id: "feature-flags",
+		title: "Feature Flags",
+		content: "Implement feature flags at the route level.",
+		examples: [
+			{
+				code: `import { createFeatureFlagManager } from '@wrikka/solid-framework/router';
+	
+	const flags = createFeatureFlagManager();
+	
+	flags.setFlag({
+	  name: 'new-dashboard',
+	  enabled: true,
+	  rolloutPercentage: 50,
+	});
+	
+	flags.addRouteFlag('/dashboard', 'new-dashboard');`,
+				description: "Feature flag setup",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["routing", "rbac"],
+	},
+];

package/src/router/modules/routing/domain/interactive-docs-core-sections.ts

@@ -0,0 +1,198 @@
+import type { DocumentationSection } from "./interactive-docs";
+
+export const coreDocumentationSections: readonly DocumentationSection[] = [
+	{
+		id: "getting-started",
+		title: "Getting Started",
+		content:
+			"Learn how to set up and use the @wrikka/solid-framework/router in your SolidJS application.",
+		examples: [
+			{
+				code: `import { createRouter } from '@wrikka/solid-framework/router';
+	
+	const router = createRouter({
+	  routes: [
+	    {
+	      path: '/',
+	      component: () => <Home />,
+	    },
+	  ],
+	});`,
+				description: "Basic router setup",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["routing", "navigation"],
+	},
+	{
+		id: "routing",
+		title: "Routing",
+		content:
+			"Understand how to define and configure routes in your application.",
+		examples: [
+			{
+				code: `const routes = [
+	  {
+	    path: '/users/:id',
+	    component: () => <UserDetail />,
+	    meta: {
+	      title: 'User Details',
+	    },
+	  },
+	];`,
+				description: "Defining routes with parameters",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["navigation", "guards"],
+	},
+	{
+		id: "navigation",
+		title: "Navigation",
+		content:
+			"Learn how to navigate between routes programmatically and through links.",
+		examples: [
+			{
+				code: `import { useNavigate } from '@wrikka/solid-framework/router';
+	
+	function MyComponent() {
+	  const navigate = useNavigate();
+	
+	  const handleClick = () => {
+	    navigate('/users/123');
+	  };
+	
+	  return <button onClick={handleClick}>Go to User</button>;
+	}`,
+				description: "Programmatic navigation",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["routing", "links"],
+	},
+	{
+		id: "guards",
+		title: "Route Guards",
+		content: "Protect routes with authentication and authorization guards.",
+		examples: [
+			{
+				code: `const authGuard = (to, from) => {
+	  if (!isAuthenticated()) {
+	    return '/login';
+	  }
+	  return true;
+	};
+	
+	const routes = [
+	  {
+	    path: '/dashboard',
+	    component: () => <Dashboard />,
+	    guards: [authGuard],
+	  },
+	];`,
+				description: "Authentication guard",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["rbac", "middleware"],
+	},
+	{
+		id: "rbac",
+		title: "Role-Based Access Control",
+		content:
+			"Implement fine-grained access control with roles and permissions.",
+		examples: [
+			{
+				code: `import { createRBACEngine } from '@wrikka/solid-framework/router';
+	
+	const rbac = createRBACEngine();
+	
+	rbac.addRole('admin', ['read', 'write', 'delete']);
+	rbac.addRole('user', ['read']);
+	
+	rbac.addPermission('edit-post', {
+	  resource: 'posts',
+	  action: 'edit',
+	  condition: (user) => user.id === post.authorId,
+	});`,
+				description: "Setting up RBAC",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["guards", "security"],
+	},
+	{
+		id: "caching",
+		title: "Route Caching",
+		content:
+			"Implement server-side and client-side caching for improved performance.",
+		examples: [
+			{
+				code: `import { createRouteCacheManager } from '@wrikka/solid-framework/router';
+	
+	const cache = createRouteCacheManager('swr', {
+	  maxSize: 100,
+	  evictionPolicy: 'lru',
+	});
+	
+	cache.set('/api/users', userData, 5000);`,
+				description: "Setting up route caching",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["performance", "preloading"],
+	},
+	{
+		id: "i18n",
+		title: "Internationalization",
+		content: "Add multi-language support to your routes.",
+		examples: [
+			{
+				code: `import { createI18nEngine } from '@wrikka/solid-framework/router';
+	
+	const i18n = createI18nEngine({
+	  defaultLocale: 'en',
+	  supportedLocales: ['en', 'th', 'ja'],
+	  detection: ['path', 'header', 'cookie'],
+	});
+	
+	i18n.addLocaleConfig('en', {
+	  translations: {
+	    home: 'Home',
+	    about: 'About',
+	  },
+	});`,
+				description: "Setting up i18n",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["routing", "middleware"],
+	},
+	{
+		id: "testing",
+		title: "Route Testing",
+		content: "Test your routes with contract testing and E2E integration.",
+		examples: [
+			{
+				code: `import { createRouteContractTester } from '@wrikka/solid-framework/router';
+	
+	const tester = createRouteContractTester();
+	
+	const contract = tester.createContract('/users/:id', {
+	  params: {
+	    id: tester.createParamSchema('string', {
+	      pattern: '^[0-9]+$',
+	    }),
+	  },
+	});
+	
+	const result = tester.validateContract(contract, {
+	  params: { id: '123' },
+	});`,
+				description: "Route contract testing",
+				language: "typescript",
+			},
+		],
+		relatedSections: ["e2e", "security"],
+	},
+];

package/src/router/modules/routing/domain/interactive-docs.ts

@@ -0,0 +1,154 @@
+import { advancedDocumentationSections } from "./interactive-docs-advanced-sections";
+import { coreDocumentationSections } from "./interactive-docs-core-sections";
+
+export interface DocumentationSection {
+	id: string;
+	title: string;
+	content: string;
+	examples: Array<{
+		code: string;
+		description: string;
+		language: string;
+	}>;
+	relatedSections: string[];
+}
+
+export interface DocumentationIndex {
+	sections: Map<string, DocumentationSection>;
+	searchIndex: Map<string, string[]>;
+}
+
+export class InteractiveDocumentation {
+	private index: DocumentationIndex = {
+		sections: new Map(),
+		searchIndex: new Map(),
+	};
+
+	constructor() {
+		this.initializeDocumentation();
+	}
+
+	private initializeDocumentation(): void {
+		for (const section of [
+			...coreDocumentationSections,
+			...advancedDocumentationSections,
+		]) {
+			this.addSection(section);
+		}
+	}
+
+	private addSection(section: DocumentationSection): void {
+		this.index.sections.set(section.id, section);
+
+		const keywords = this.extractKeywords(
+			`${section.title} ${section.content}`,
+		);
+		for (const keyword of keywords) {
+			const existing = this.index.searchIndex.get(keyword) || [];
+			if (!existing.includes(section.id)) {
+				existing.push(section.id);
+			}
+			this.index.searchIndex.set(keyword, existing);
+		}
+	}
+
+	private extractKeywords(text: string): string[] {
+		return text
+			.toLowerCase()
+			.split(/\s+/)
+			.filter((word) => word.length > 3);
+	}
+
+	getSection(id: string): DocumentationSection | undefined {
+		return this.index.sections.get(id);
+	}
+
+	getAllSections(): DocumentationSection[] {
+		return Array.from(this.index.sections.values());
+	}
+
+	search(query: string): DocumentationSection[] {
+		const keywords = this.extractKeywords(query);
+		const sectionIds = new Set<string>();
+
+		for (const keyword of keywords) {
+			const ids = this.index.searchIndex.get(keyword) || [];
+			for (const id of ids) {
+				sectionIds.add(id);
+			}
+		}
+
+		return Array.from(sectionIds)
+			.map((id) => this.index.sections.get(id))
+			.filter(
+				(section): section is DocumentationSection => section !== undefined,
+			);
+	}
+
+	getRelatedSections(sectionId: string): DocumentationSection[] {
+		const section = this.index.sections.get(sectionId);
+		if (!section) return [];
+
+		return section.relatedSections
+			.map((id) => this.index.sections.get(id))
+			.filter((s): s is DocumentationSection => s !== undefined);
+	}
+
+	getTableOfContents(): Array<{
+		id: string;
+		title: string;
+		relatedSections: string[];
+	}> {
+		return Array.from(this.index.sections.values()).map((section) => ({
+			id: section.id,
+			title: section.title,
+			relatedSections: section.relatedSections,
+		}));
+	}
+
+	generateDocumentation(): string {
+		let output = "# @wrikka/solid-framework/router Documentation\n\n";
+		output += "## Table of Contents\n\n";
+
+		const toc = this.getTableOfContents();
+		for (const item of toc) {
+			output += `- [${item.title}](#${item.id})\n`;
+		}
+
+		output += "\n---\n\n";
+
+		for (const section of this.index.sections.values()) {
+			output += `## ${section.title}\n\n`;
+			output += `${section.content}\n\n`;
+
+			if (section.examples.length > 0) {
+				output += "### Examples\n\n";
+				for (const example of section.examples) {
+					output += `${example.description}\n\n`;
+					output += `\`\`\`${example.language}\n`;
+					output += `${example.code}\n`;
+					output += "```\n\n";
+				}
+			}
+
+			if (section.relatedSections.length > 0) {
+				output += "### Related Sections\n\n";
+				for (const relatedId of section.relatedSections) {
+					const related = this.index.sections.get(relatedId);
+					if (related) {
+						output += `- [${related.title}](#${related.id})\n`;
+					}
+				}
+				output += "\n";
+			}
+
+			output += "---\n\n";
+		}
+
+		return output;
+	}
+}
+
+export const createInteractiveDocumentation = (): InteractiveDocumentation => {
+	return new InteractiveDocumentation();
+};

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

@@ -0,0 +1,35 @@
+export type ISRConfig = {
+	path: string;
+	revalidateAfter: number; // seconds
+};
+
+export class ISRManager {
+	private isrConfigs: Map<string, ISRConfig> = new Map();
+	private lastRevalidated: Map<string, number> = new Map();
+
+	setISRConfig(config: ISRConfig): void {
+		this.isrConfigs.set(config.path, config);
+	}
+
+	shouldRevalidate(path: string, now: number): boolean {
+		const config = this.isrConfigs.get(path);
+		if (!config) return false;
+
+		const lastRevalidated = this.lastRevalidated.get(path) || 0;
+		const elapsed = (now - lastRevalidated) / 1000;
+
+		return elapsed >= config.revalidateAfter;
+	}
+
+	markRevalidated(path: string, now: number): void {
+		this.lastRevalidated.set(path, now);
+	}
+
+	getISRConfig(path: string): ISRConfig | undefined {
+		return this.isrConfigs.get(path);
+	}
+}
+
+export const createISRManager = (): ISRManager => {
+	return new ISRManager();
+};

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

@@ -0,0 +1,79 @@
+import type { RouteMatch } from "../../../shared/types";
+import { failure, type Result, success } from "../../../shared/types";
+
+export type Middleware = (
+	match: RouteMatch,
+	next: () => Result<void> | Promise<Result<void>>,
+) => Result<void> | Promise<Result<void>>;
+
+export interface MiddlewareLogger {
+	log: (message: string) => void;
+}
+
+export class MiddlewareManager {
+	private middlewares: Map<string, Middleware[]> = new Map();
+	private globalMiddlewares: Middleware[] = [];
+
+	addMiddleware(path: string, middleware: Middleware): void {
+		const existing = this.middlewares.get(path) || [];
+		this.middlewares.set(path, [...existing, middleware]);
+	}
+
+	addGlobalMiddleware(middleware: Middleware): void {
+		this.globalMiddlewares.push(middleware);
+	}
+
+	async executeMiddleware(match: RouteMatch): Promise<Result<void>> {
+		const middlewares = [
+			...this.globalMiddlewares,
+			...(this.middlewares.get(match.path) || []),
+		];
+
+		let index = 0;
+
+		const next = (): Result<void> | Promise<Result<void>> => {
+			if (index >= middlewares.length) {
+				return success(undefined);
+			}
+			const middleware = middlewares[index++];
+			const result = middleware(match, next);
+			return result;
+		};
+
+		for (const middleware of middlewares) {
+			const result = await middleware(match, next);
+			if (!result.success) {
+				return result;
+			}
+		}
+
+		return success(undefined);
+	}
+}
+
+export const createMiddlewareManager = (): MiddlewareManager => {
+	return new MiddlewareManager();
+};
+
+export const createAuthMiddleware = (
+	isAuthenticated: () => boolean | Promise<boolean>,
+): Middleware => {
+	return async (_match, next) => {
+		const authenticated = await isAuthenticated();
+		if (!authenticated) {
+			return failure(new Error("Authentication required"));
+		}
+		return next();
+	};
+};
+
+export const createLoggingMiddleware = (
+	logger?: MiddlewareLogger,
+): Middleware => {
+	return (match, next) => {
+		if (logger) {
+			logger.log(`Navigating to: ${match.path}`);
+		}
+		return next();
+	};
+};