@ripple-ts/vite-plugin 0.2.210 → 0.2.212

package/src/server/router.js

@@ -0,0 +1,122 @@
+/**
+ * @typedef {import('@ripple-ts/vite-plugin').Route} Route
+ * @typedef {import('@ripple-ts/vite-plugin').RenderRoute} RenderRoute
+ * @typedef {import('@ripple-ts/vite-plugin').ServerRoute} ServerRoute
+ */
+
+/**
+ * @typedef {Object} RouteMatch
+ * @property {Route} route
+ * @property {Record<string, string>} params
+ */
+
+/**
+ * @typedef {Object} CompiledRoute
+ * @property {Route} route
+ * @property {RegExp} pattern
+ * @property {string[]} paramNames
+ * @property {number} specificity - Higher = more specific (static > param > catch-all)
+ */
+
+/**
+ * Convert a route path pattern to a RegExp
+ * Supports:
+ * - Static segments: /about, /api/hello
+ * - Named params: /posts/:id, /users/:userId/posts/:postId
+ * - Catch-all: /docs/*slug
+ *
+ * @param {string} path
+ * @returns {{ pattern: RegExp, paramNames: string[], specificity: number }}
+ */
+function compilePath(path) {
+	/** @type {string[]} */
+	const paramNames = [];
+	let specificity = 0;
+
+	// Escape special regex characters except our param syntax
+	const regexString = path
+		.split('/')
+		.map((segment) => {
+			if (!segment) return '';
+
+			// Catch-all param: *slug
+			if (segment.startsWith('*')) {
+				const paramName = segment.slice(1);
+				paramNames.push(paramName);
+				specificity += 1; // Lowest specificity
+				return '(.+)';
+			}
+
+			// Named param: :id
+			if (segment.startsWith(':')) {
+				const paramName = segment.slice(1);
+				paramNames.push(paramName);
+				specificity += 10; // Medium specificity
+				return '([^/]+)';
+			}
+
+			// Static segment
+			specificity += 100; // Highest specificity
+			return escapeRegex(segment);
+		})
+		.join('/');
+
+	const pattern = new RegExp(`^${regexString || '/'}$`);
+	return { pattern, paramNames, specificity };
+}
+
+/**
+ * Escape special regex characters
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeRegex(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Create a router from a list of routes
+ * @param {Route[]} routes
+ * @returns {{ match: (method: string, pathname: string) => RouteMatch | null }}
+ */
+export function createRouter(routes) {
+	/** @type {CompiledRoute[]} */
+	const compiledRoutes = routes.map((route) => {
+		const { pattern, paramNames, specificity } = compilePath(route.path);
+		return { route, pattern, paramNames, specificity };
+	});
+
+	// Sort by specificity (higher first) for correct matching order
+	compiledRoutes.sort((a, b) => b.specificity - a.specificity);
+
+	return {
+		/**
+		 * Match a request to a route
+		 * @param {string} method
+		 * @param {string} pathname
+		 * @returns {RouteMatch | null}
+		 */
+		match(method, pathname) {
+			for (const { route, pattern, paramNames } of compiledRoutes) {
+				// Check method for ServerRoute
+				if (route.type === 'server') {
+					const methods = /** @type {ServerRoute} */ (route).methods;
+					if (!methods.includes(method.toUpperCase())) {
+						continue;
+					}
+				}
+
+				const match = pathname.match(pattern);
+				if (match) {
+					/** @type {Record<string, string>} */
+					const params = {};
+					for (let i = 0; i < paramNames.length; i++) {
+						params[paramNames[i]] = decodeURIComponent(match[i + 1]);
+					}
+					return { route, params };
+				}
+			}
+			return null;
+		},
+	};
+}

package/src/server/server-route.js

@@ -0,0 +1,46 @@
+/**
+ * @typedef {import('@ripple-ts/vite-plugin').Context} Context
+ * @typedef {import('@ripple-ts/vite-plugin').ServerRoute} ServerRoute
+ * @typedef {import('@ripple-ts/vite-plugin').Middleware} Middleware
+ */
+
+import { runMiddlewareChain } from './middleware.js';
+
+/**
+ * Handle a ServerRoute (API endpoint)
+ *
+ * @param {ServerRoute} route
+ * @param {Context} context
+ * @param {Middleware[]} globalMiddlewares
+ * @returns {Promise<Response>}
+ */
+export async function handleServerRoute(route, context, globalMiddlewares) {
+	try {
+		// The handler wrapped as a function returning Promise<Response>
+		const handler = async () => {
+			return route.handler(context);
+		};
+
+		// Run the middleware chain: global → before → handler → after
+		const response = await runMiddlewareChain(
+			context,
+			globalMiddlewares,
+			route.before,
+			handler,
+			route.after,
+		);
+
+		return response;
+	} catch (error) {
+		console.error('[ripple] API route error:', error);
+
+		// Return error response
+		const message = error instanceof Error ? error.message : 'Internal Server Error';
+		return new Response(JSON.stringify({ error: message }), {
+			status: 500,
+			headers: {
+				'Content-Type': 'application/json',
+			},
+		});
+	}
+}

package/types/index.d.ts

@@ -1,9 +1,125 @@
 import type { Plugin } from 'vite';
 
 declare module '@ripple-ts/vite-plugin' {
+	// ============================================================================
+	// Plugin exports
+	// ============================================================================
+
 	export function ripple(options?: RipplePluginOptions): Plugin[];
+	export function defineConfig(options: RippleConfigOptions): RippleConfigOptions;
+
+	// ============================================================================
+	// Route classes
+	// ============================================================================
+
+	export class RenderRoute {
+		readonly type: 'render';
+		path: string;
+		entry: string;
+		layout?: string;
+		before: Middleware[];
+		constructor(options: RenderRouteOptions);
+	}
+
+	export class ServerRoute {
+		readonly type: 'server';
+		path: string;
+		methods: string[];
+		handler: RouteHandler;
+		before: Middleware[];
+		after: Middleware[];
+		constructor(options: ServerRouteOptions);
+	}
+
+	export type Route = RenderRoute | ServerRoute;
+
+	// ============================================================================
+	// Route options
+	// ============================================================================
+
+	export interface RenderRouteOptions {
+		/** URL path pattern (e.g., '/', '/posts/:id', '/docs/*slug') */
+		path: string;
+		/** Path to the Ripple component entry file */
+		entry: string;
+		/** Path to the layout component (wraps the entry) */
+		layout?: string;
+		/** Middleware to run before rendering */
+		before?: Middleware[];
+	}
+
+	export interface ServerRouteOptions {
+		/** URL path pattern (e.g., '/api/hello', '/api/posts/:id') */
+		path: string;
+		/** HTTP methods to handle (default: ['GET']) */
+		methods?: string[];
+		/** Request handler that returns a Response */
+		handler: RouteHandler;
+		/** Middleware to run before the handler */
+		before?: Middleware[];
+		/** Middleware to run after the handler */
+		after?: Middleware[];
+	}
+
+	// ============================================================================
+	// Context and middleware
+	// ============================================================================
+
+	export interface Context {
+		/** The incoming Request object */
+		request: Request;
+		/** URL parameters extracted from the route pattern */
+		params: Record<string, string>;
+		/** Parsed URL object */
+		url: URL;
+		/** Shared state for passing data between middlewares */
+		state: Map<string, unknown>;
+	}
+
+	export type NextFunction = () => Promise<Response>;
+	export type Middleware = (context: Context, next: NextFunction) => Response | Promise<Response>;
+	export type RouteHandler = (context: Context) => Response | Promise<Response>;
+
+	// ============================================================================
+	// Configuration
+	// ============================================================================
 
 	export interface RipplePluginOptions {
 		excludeRippleExternalModules?: boolean;
 	}
+
+	export interface RippleConfigOptions {
+		build?: {
+			minify?: boolean;
+		};
+		adapter?: {
+			serve: AdapterServeFunction;
+		};
+		router: {
+			routes: Route[];
+		};
+		/** Global middlewares applied to all routes */
+		middlewares?: Middleware[];
+		platform?: {
+			env: Record<string, string>;
+		};
+		server?: {
+			/**
+			 * Whether to trust `X-Forwarded-Proto` and `X-Forwarded-Host` headers
+			 * when deriving the request origin (protocol + host).
+			 *
+			 * Enable this only when the application is behind a trusted reverse proxy
+			 * (e.g., nginx, Cloudflare, AWS ALB). When `false` (the default), the
+			 * protocol is inferred from the socket and the host from the `Host` header.
+			 *
+			 * @default false
+			 */
+			trustProxy?: boolean;
+		};
+	}
+
+	export type AdapterServeFunction = (
+		handler: (request: Request, platform?: unknown) => Response | Promise<Response>,
+		options?: Record<string, unknown>,
+	) => { listen: (port?: number) => unknown; close: () => void };
 }