litestar-vite-plugin 0.14.0 → 0.15.0-alpha.1

package/dist/js/helpers/routes.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Route utilities for Litestar applications.
+ *
+ * These helpers work with route metadata injected by Litestar:
+ * - window.__LITESTAR_ROUTES__ (SPA mode with route injection)
+ * - window.routes (legacy/Inertia mode)
+ * - Generated routes from src/generated/routes.ts (typed routing)
+ *
+ * For typed routing, import from your generated routes instead:
+ * ```ts
+ * import { route, routes } from '@/generated/routes'
+ * ```
+ *
+ * @module
+ */
+/**
+ * Route definition from Litestar.
+ */
+export interface RouteDefinition {
+    uri: string;
+    methods: string[];
+    parameters?: string[];
+    parameterTypes?: Record<string, string>;
+    queryParameters?: Record<string, string>;
+    component?: string;
+}
+/**
+ * Routes object mapping route names to definitions.
+ */
+export interface RoutesMap {
+    routes: Record<string, RouteDefinition>;
+}
+/**
+ * Convenience alias for route names when using injected metadata.
+ */
+export type RouteName = keyof RoutesMap["routes"];
+declare global {
+    interface Window {
+        __LITESTAR_ROUTES__?: RoutesMap;
+        routes?: Record<string, string>;
+        serverRoutes?: Record<string, string>;
+    }
+    var routes: Record<string, string>;
+    var serverRoutes: Record<string, string>;
+}
+declare global {
+    interface ImportMeta {
+        hot?: {
+            on: (event: string, callback: (...args: unknown[]) => void) => void;
+            accept?: (cb?: () => void) => void;
+        };
+    }
+}
+type RouteArg = string | number | boolean;
+type RouteArgs = Record<string, RouteArg> | RouteArg[];
+/**
+ * Get the routes object from the page.
+ *
+ * Checks multiple sources:
+ * 1. window.__LITESTAR_ROUTES__ (SPA mode with full metadata)
+ * 2. window.routes (legacy mode with just paths)
+ *
+ * @returns Routes map or null if not found
+ */
+export declare function getRoutes(): Record<string, string> | null;
+/**
+ * Generate a URL for a named route with parameters.
+ *
+ * @param routeName - The name of the route
+ * @param args - Route parameters (object or array)
+ * @returns The generated URL or "#" if route not found
+ *
+ * @example
+ * ```ts
+ * import { route } from 'litestar-vite-plugin/helpers'
+ *
+ * // Named parameters
+ * route('user:detail', { user_id: 123 })  // "/users/123"
+ *
+ * // Positional parameters
+ * route('user:detail', [123])  // "/users/123"
+ * ```
+ */
+export declare function route(routeName: string, ...args: [RouteArgs?]): string;
+/**
+ * Get the relative path portion of a URL.
+ *
+ * @param url - Full URL or path
+ * @returns Relative path with query string and hash
+ */
+export declare function getRelativeUrlPath(url: string): string;
+/**
+ * Convert a URL to a route name.
+ *
+ * @param url - URL to match
+ * @returns Route name or null if no match
+ *
+ * @example
+ * ```ts
+ * toRoute('/users/123')  // "user:detail"
+ * ```
+ */
+export declare function toRoute(url: string): string | null;
+/**
+ * Get the current route name based on window.location.
+ *
+ * @returns Current route name or null if no match
+ */
+export declare function currentRoute(): string | null;
+/**
+ * Check if a URL matches a route pattern.
+ *
+ * Supports wildcard patterns like "user:*" to match "user:list", "user:detail", etc.
+ *
+ * @param url - URL to check
+ * @param routeName - Route name or pattern (supports * wildcards)
+ * @returns True if the URL matches the route
+ *
+ * @example
+ * ```ts
+ * isRoute('/users/123', 'user:detail')  // true
+ * isRoute('/users/123', 'user:*')       // true
+ * ```
+ */
+export declare function isRoute(url: string, routeName: string): boolean;
+/**
+ * Check if the current URL matches a route pattern.
+ *
+ * @param routeName - Route name or pattern (supports * wildcards)
+ * @returns True if the current URL matches the route
+ *
+ * @example
+ * ```ts
+ * // On /users/123
+ * isCurrentRoute('user:detail')  // true
+ * isCurrentRoute('user:*')       // true
+ * ```
+ */
+export declare function isCurrentRoute(routeName: string): boolean;
+export {};

package/dist/js/helpers/routes.js

@@ -0,0 +1,280 @@
+/**
+ * Route utilities for Litestar applications.
+ *
+ * These helpers work with route metadata injected by Litestar:
+ * - window.__LITESTAR_ROUTES__ (SPA mode with route injection)
+ * - window.routes (legacy/Inertia mode)
+ * - Generated routes from src/generated/routes.ts (typed routing)
+ *
+ * For typed routing, import from your generated routes instead:
+ * ```ts
+ * import { route, routes } from '@/generated/routes'
+ * ```
+ *
+ * @module
+ */
+/**
+ * Get the routes object from the page.
+ *
+ * Checks multiple sources:
+ * 1. window.__LITESTAR_ROUTES__ (SPA mode with full metadata)
+ * 2. window.routes (legacy mode with just paths)
+ *
+ * @returns Routes map or null if not found
+ */
+export function getRoutes() {
+    if (typeof window === "undefined") {
+        return null;
+    }
+    // Check for full route metadata (SPA mode)
+    if (window.__LITESTAR_ROUTES__?.routes) {
+        const routes = {};
+        for (const [name, def] of Object.entries(window.__LITESTAR_ROUTES__.routes)) {
+            routes[name] = def.uri;
+        }
+        // Expose a descriptive alias for consumers
+        window.serverRoutes = routes;
+        return routes;
+    }
+    // Check for simple routes object (legacy/Inertia mode)
+    if (window.routes) {
+        return window.routes;
+    }
+    // Check globalThis.routes
+    if (typeof globalThis !== "undefined" && globalThis.routes) {
+        return globalThis.routes;
+    }
+    return null;
+}
+/**
+ * Generate a URL for a named route with parameters.
+ *
+ * @param routeName - The name of the route
+ * @param args - Route parameters (object or array)
+ * @returns The generated URL or "#" if route not found
+ *
+ * @example
+ * ```ts
+ * import { route } from 'litestar-vite-plugin/helpers'
+ *
+ * // Named parameters
+ * route('user:detail', { user_id: 123 })  // "/users/123"
+ *
+ * // Positional parameters
+ * route('user:detail', [123])  // "/users/123"
+ * ```
+ */
+export function route(routeName, ...args) {
+    const routes = getRoutes();
+    if (!routes) {
+        console.error("Routes not available. Ensure route metadata is injected.");
+        return "#";
+    }
+    let url = routes[routeName];
+    if (!url) {
+        console.error(`Route '${routeName}' not found.`);
+        return "#";
+    }
+    const argTokens = url.match(/\{([^}]+)\}/g);
+    if (!argTokens && args.length > 0 && args[0] !== undefined) {
+        console.error(`Route '${routeName}' does not accept parameters.`);
+        return "#";
+    }
+    if (!argTokens) {
+        return new URL(url, window.location.origin).href;
+    }
+    try {
+        if (typeof args[0] === "object" && !Array.isArray(args[0])) {
+            // Named parameters
+            for (const token of argTokens) {
+                let argName = token.slice(1, -1);
+                // Handle {param:type} syntax
+                if (argName.includes(":")) {
+                    argName = argName.split(":")[0];
+                }
+                const argValue = args[0][argName];
+                if (argValue === undefined) {
+                    throw new Error(`Missing parameter '${argName}'.`);
+                }
+                url = url.replace(token, String(argValue));
+            }
+        }
+        else {
+            // Positional parameters
+            const argsArray = Array.isArray(args[0]) ? args[0] : Array.from(args);
+            if (argTokens.length !== argsArray.length) {
+                throw new Error(`Expected ${argTokens.length} parameters, got ${argsArray.length}.`);
+            }
+            argTokens.forEach((token, i) => {
+                const argValue = argsArray[i];
+                if (argValue === undefined) {
+                    throw new Error(`Missing parameter at position ${i}.`);
+                }
+                url = url.replace(token, String(argValue));
+            });
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return "#";
+    }
+    return new URL(url, window.location.origin).href;
+}
+/**
+ * Get the relative path portion of a URL.
+ *
+ * @param url - Full URL or path
+ * @returns Relative path with query string and hash
+ */
+export function getRelativeUrlPath(url) {
+    try {
+        const urlObject = new URL(url);
+        return urlObject.pathname + urlObject.search + urlObject.hash;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Convert a URL to a route name.
+ *
+ * @param url - URL to match
+ * @returns Route name or null if no match
+ *
+ * @example
+ * ```ts
+ * toRoute('/users/123')  // "user:detail"
+ * ```
+ */
+export function toRoute(url) {
+    const routes = getRoutes();
+    if (!routes) {
+        return null;
+    }
+    const processedUrl = getRelativeUrlPath(url);
+    const normalizedUrl = processedUrl === "/" ? processedUrl : processedUrl.replace(/\/$/, "");
+    for (const [routeName, routePattern] of Object.entries(routes)) {
+        const regexPattern = routePattern.replace(/\//g, "\\/").replace(/\{([^}]+)\}/g, (_, paramSpec) => {
+            // Handle {param:type} syntax
+            const paramType = paramSpec.includes(":") ? paramSpec.split(":")[1] : "str";
+            switch (paramType) {
+                case "uuid":
+                    return "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+                case "path":
+                    return ".*";
+                case "int":
+                    return "\\d+";
+                default:
+                    return "[^/]+";
+            }
+        });
+        const regex = new RegExp(`^${regexPattern}$`);
+        if (regex.test(normalizedUrl)) {
+            return routeName;
+        }
+    }
+    return null;
+}
+/**
+ * Get the current route name based on window.location.
+ *
+ * @returns Current route name or null if no match
+ */
+export function currentRoute() {
+    if (typeof window === "undefined") {
+        return null;
+    }
+    return toRoute(window.location.pathname);
+}
+/**
+ * Check if a URL matches a route pattern.
+ *
+ * Supports wildcard patterns like "user:*" to match "user:list", "user:detail", etc.
+ *
+ * @param url - URL to check
+ * @param routeName - Route name or pattern (supports * wildcards)
+ * @returns True if the URL matches the route
+ *
+ * @example
+ * ```ts
+ * isRoute('/users/123', 'user:detail')  // true
+ * isRoute('/users/123', 'user:*')       // true
+ * ```
+ */
+export function isRoute(url, routeName) {
+    const routes = getRoutes();
+    if (!routes) {
+        return false;
+    }
+    const processedUrl = getRelativeUrlPath(url);
+    const normalizedUrl = processedUrl === "/" ? processedUrl : processedUrl.replace(/\/$/, "");
+    // Convert route name pattern to regex
+    const routeNameRegex = new RegExp(`^${routeName.replace(/\*/g, ".*")}$`);
+    // Find all matching route names based on the pattern
+    const matchingRouteNames = Object.keys(routes).filter((name) => routeNameRegex.test(name));
+    for (const name of matchingRouteNames) {
+        const routePattern = routes[name];
+        const regexPattern = routePattern.replace(/\//g, "\\/").replace(/\{([^}]+)\}/g, (_, paramSpec) => {
+            const paramType = paramSpec.includes(":") ? paramSpec.split(":")[1] : "str";
+            switch (paramType) {
+                case "uuid":
+                    return "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+                case "path":
+                    return "(.*)";
+                case "int":
+                    return "(\\d+)";
+                default:
+                    return "([^/]+)";
+            }
+        });
+        const regex = new RegExp(`^${regexPattern}$`);
+        if (regex.test(normalizedUrl)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if the current URL matches a route pattern.
+ *
+ * @param routeName - Route name or pattern (supports * wildcards)
+ * @returns True if the current URL matches the route
+ *
+ * @example
+ * ```ts
+ * // On /users/123
+ * isCurrentRoute('user:detail')  // true
+ * isCurrentRoute('user:*')       // true
+ * ```
+ */
+export function isCurrentRoute(routeName) {
+    const current = currentRoute();
+    if (!current) {
+        return false;
+    }
+    const routeNameRegex = new RegExp(`^${routeName.replace(/\*/g, ".*")}$`);
+    return routeNameRegex.test(current);
+}
+// Set up global functions for backward compatibility
+if (typeof globalThis !== "undefined") {
+    globalThis.routes = globalThis.routes || {};
+    globalThis.serverRoutes = globalThis.serverRoutes || globalThis.routes;
+    globalThis.route = route;
+    globalThis.toRoute = toRoute;
+    globalThis.currentRoute = currentRoute;
+    globalThis.isRoute = isRoute;
+    globalThis.isCurrentRoute = isCurrentRoute;
+}
+// Keep serverRoutes fresh during Vite HMR when the plugin regenerates metadata/types
+if (import.meta.hot) {
+    import.meta.hot.on("litestar:types-updated", () => {
+        if (typeof window === "undefined") {
+            return;
+        }
+        const updated = getRoutes();
+        if (updated) {
+            window.serverRoutes = updated;
+            window.routes = updated;
+        }
+    });
+}

package/dist/js/index.d.ts

@@ -1,6 +1,63 @@
 import { type ConfigEnv, type Plugin, type UserConfig } from "vite";
 import { type Config as FullReloadConfig } from "vite-plugin-full-reload";
-interface PluginConfig {
+/**
+ * Configuration for TypeScript type generation.
+ *
+ * Type generation works as follows:
+ * 1. Python's Litestar exports openapi.json and routes.json on startup (and reload)
+ * 2. The Vite plugin watches these files for changes
+ * 3. When they change, it runs @hey-api/openapi-ts to generate TypeScript types
+ * 4. HMR event is sent to notify the client
+ */
+export interface TypesConfig {
+    /**
+     * Enable type generation.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Path to output generated TypeScript types.
+     *
+     * @default 'src/types/api'
+     */
+    output?: string;
+    /**
+     * Path where the OpenAPI schema is exported by Litestar.
+     * The Vite plugin watches this file and runs @hey-api/openapi-ts when it changes.
+     *
+     * @default 'openapi.json'
+     */
+    openapiPath?: string;
+    /**
+     * Path where route metadata is exported by Litestar.
+     * The Vite plugin watches this file for route helper generation.
+     *
+     * @default 'routes.json'
+     */
+    routesPath?: string;
+    /**
+     * Generate Zod schemas in addition to TypeScript types.
+     *
+     * @default false
+     */
+    generateZod?: boolean;
+    /**
+     * Generate a typed SDK client (fetch) in addition to types.
+     *
+     * @default false
+     */
+    generateSdk?: boolean;
+    /**
+     * Debounce time in milliseconds for type regeneration.
+     * Prevents regeneration from running too frequently when
+     * multiple files are written in quick succession.
+     *
+     * @default 300
+     */
+    debounce?: number;
+}
+export interface PluginConfig {
     /**
      * The path or paths of the entry points to compile.
      */
@@ -62,6 +119,34 @@ interface PluginConfig {
      * Transform the code while serving.
      */
     transformOnServe?: (code: string, url: DevServerUrl) => string;
+    /**
+     * Enable and configure TypeScript type generation.
+     *
+     * When set to `true`, enables type generation with default settings.
+     * When set to a TypesConfig object, enables type generation with custom settings.
+     *
+     * Type generation creates TypeScript types from your Litestar OpenAPI schema
+     * and route metadata using @hey-api/openapi-ts.
+     *
+     * @example
+     * ```ts
+     * // Simple enable
+     * litestar({ input: 'src/main.ts', types: true })
+     *
+     * // With custom config
+     * litestar({
+     *   input: 'src/main.ts',
+     *   types: {
+     *     enabled: true,
+     *     output: 'src/api/types',
+     *     generateZod: true
+     *   }
+     * })
+     * ```
+     *
+     * @default false
+     */
+    types?: boolean | TypesConfig;
 }
 interface RefreshConfig {
     paths: string[];