litestar-vite-plugin 0.15.0-alpha.4 → 0.15.0-alpha.5

package/dist/js/astro.d.ts

@@ -125,6 +125,12 @@ export interface AstroTypesConfig {
      * @default false
      */
     generateZod?: boolean;
+    /**
+     * Generate SDK client functions for API calls.
+     *
+     * @default true
+     */
+    generateSdk?: boolean;
     /**
      * Debounce time in milliseconds for type regeneration.
      *

package/dist/js/astro.js

@@ -40,6 +40,7 @@ function resolveConfig(config = {}) {
       openapiPath: "openapi.json",
       routesPath: "routes.json",
       generateZod: false,
+      generateSdk: true,
       debounce: 300
     };
   } else if (typeof config.types === "object" && config.types !== null) {
@@ -49,6 +50,7 @@ function resolveConfig(config = {}) {
       openapiPath: config.types.openapiPath ?? "openapi.json",
       routesPath: config.types.routesPath ?? "routes.json",
       generateZod: config.types.generateZod ?? false,
+      generateSdk: config.types.generateSdk ?? true,
       debounce: config.types.debounce ?? 300
     };
   }
@@ -68,6 +70,9 @@ function createProxyPlugin(config) {
     config() {
       return {
         server: {
+          // Force IPv4 binding for consistency with Python proxy configuration
+          // Without this, Astro might bind to IPv6 localhost which the proxy can't reach
+          host: "127.0.0.1",
           // Set the port from Python config/env to ensure Astro uses the expected port
           // strictPort: true prevents Astro from auto-incrementing to a different port
           ...config.port !== void 0 ? {
@@ -227,12 +232,28 @@ function createTypeGenerationPlugin(typesConfig) {
         return false;
       }
       console.log(colors.cyan("[litestar-astro]"), colors.dim("Generating TypeScript types..."));
-      const args = ["@hey-api/openapi-ts", "-i", typesConfig.openapiPath, "-o", typesConfig.output];
-      if (typesConfig.generateZod) {
-        args.push("--plugins", "zod", "@hey-api/typescript");
+      const projectRoot = process.cwd();
+      const candidates = [path.resolve(projectRoot, "openapi-ts.config.ts"), path.resolve(projectRoot, "hey-api.config.ts"), path.resolve(projectRoot, ".hey-api.config.ts")];
+      const configPath = candidates.find((p) => fs.existsSync(p)) || null;
+      let args;
+      if (configPath) {
+        console.log(colors.cyan("[litestar-astro]"), colors.dim("Using config:"), configPath);
+        args = ["@hey-api/openapi-ts", "--file", configPath];
+      } else {
+        args = ["@hey-api/openapi-ts", "-i", typesConfig.openapiPath, "-o", typesConfig.output];
+        const plugins = ["@hey-api/typescript", "@hey-api/schemas"];
+        if (typesConfig.generateSdk) {
+          plugins.push("@hey-api/sdk", "@hey-api/client-fetch");
+        }
+        if (typesConfig.generateZod) {
+          plugins.push("zod");
+        }
+        if (plugins.length) {
+          args.push("--plugins", ...plugins);
+        }
       }
       await execAsync(`npx ${args.join(" ")}`, {
-        cwd: process.cwd()
+        cwd: projectRoot
       });
       const routesPath = path.resolve(process.cwd(), typesConfig.routesPath);
       if (fs.existsSync(routesPath)) {
@@ -271,6 +292,14 @@ function createTypeGenerationPlugin(typesConfig) {
       server = devServer;
       console.log(colors.cyan("[litestar-astro]"), colors.dim("Watching for schema changes:"), colors.yellow(typesConfig.openapiPath));
     },
+    async buildStart() {
+      if (typesConfig.enabled) {
+        const openapiPath = path.resolve(process.cwd(), typesConfig.openapiPath);
+        if (fs.existsSync(openapiPath)) {
+          await runTypeGeneration();
+        }
+      }
+    },
     handleHotUpdate({ file }) {
       if (!typesConfig.enabled) {
         return;
@@ -311,12 +340,18 @@ function litestarAstro(userConfig = {}) {
             plugins
           }
         };
-        if (command === "dev" && config.port !== void 0) {
+        if (command === "dev") {
           configUpdate.server = {
-            port: config.port
+            // Force IPv4 binding for consistency with Python proxy configuration
+            host: "127.0.0.1",
+            // Set port from Python config/env if provided
+            ...config.port !== void 0 ? { port: config.port } : {}
           };
           if (config.verbose) {
-            logger.info(`Setting Astro server port to ${config.port}`);
+            logger.info("Setting Astro server host to 127.0.0.1");
+            if (config.port !== void 0) {
+              logger.info(`Setting Astro server port to ${config.port}`);
+            }
           }
         }
         updateConfig(configUpdate);

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

@@ -0,0 +1,68 @@
+/**
+ * Litestar HTMX Extension
+ *
+ * Lightweight JSON templating for HTMX with CSRF support.
+ *
+ * Features:
+ * - `hx-swap="json"` - Client-side JSON templating
+ * - Automatic CSRF token injection
+ * - Template syntax: `ls-for`, `ls-if`, `:attr`, `@event`, `${expr}`
+ *
+ * For typed routes, import from your generated routes file:
+ * ```ts
+ * import { route } from '@/generated/routes'
+ * ```
+ *
+ * @example
+ * ```html
+ * <div hx-get="/api/books" hx-swap="json" hx-ext="litestar">
+ *   <template ls-for="book in $data">
+ *     <article :id="`book-${book.id}`">
+ *       <h3>${book.title}</h3>
+ *       <p>${book.author} • ${book.year}</p>
+ *     </article>
+ *   </template>
+ * </div>
+ * ```
+ *
+ * @module
+ */
+/** Type for route function - matches generated routes.ts */
+type RouteFn = (name: string, params?: Record<string, string | number>) => string;
+declare global {
+    interface Window {
+        htmx?: HtmxApi;
+    }
+}
+interface HtmxApi {
+    defineExtension: (name: string, ext: HtmxExtension) => void;
+    process: (elt: Element) => void;
+}
+interface HtmxExtension {
+    init?: () => void;
+    onEvent?: (name: string, evt: CustomEvent) => boolean | void;
+    transformResponse?: (text: string, xhr: XMLHttpRequest, elt: Element) => string;
+    isInlineSwap?: (swapStyle: string) => boolean;
+    handleSwap?: (swapStyle: string, target: Element, fragment: DocumentFragment | Element) => Element[];
+}
+/** Template context - inherits from data via prototype for direct access */
+interface Ctx {
+    $data: unknown;
+    $parent?: Ctx;
+    $index?: number;
+    $key?: string;
+    $event?: Event;
+    route?: RouteFn;
+    navigate?: (name: string, params?: Record<string, string | number>) => void;
+    [key: string]: unknown;
+}
+export declare function registerHtmxExtension(): void;
+export declare function swapJson(el: Element, data: unknown): void;
+type Handler = (ctx: Ctx, el: Element) => Ctx | false | void;
+interface Dir {
+    match: (a: Attr) => boolean;
+    create: (el: Element, a: Attr) => Handler | null;
+}
+export declare function setDebug(_on: boolean): void;
+export declare function addDirective(dir: Dir): void;
+export {};

package/dist/js/helpers/htmx.js

@@ -0,0 +1,494 @@
+/**
+ * Litestar HTMX Extension
+ *
+ * Lightweight JSON templating for HTMX with CSRF support.
+ *
+ * Features:
+ * - `hx-swap="json"` - Client-side JSON templating
+ * - Automatic CSRF token injection
+ * - Template syntax: `ls-for`, `ls-if`, `:attr`, `@event`, `${expr}`
+ *
+ * For typed routes, import from your generated routes file:
+ * ```ts
+ * import { route } from '@/generated/routes'
+ * ```
+ *
+ * @example
+ * ```html
+ * <div hx-get="/api/books" hx-swap="json" hx-ext="litestar">
+ *   <template ls-for="book in $data">
+ *     <article :id="`book-${book.id}`">
+ *       <h3>${book.title}</h3>
+ *       <p>${book.author} • ${book.year}</p>
+ *     </article>
+ *   </template>
+ * </div>
+ * ```
+ *
+ * @module
+ */
+import { getCsrfToken } from "./csrf.js";
+const DEBUG = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+const cache = new Map();
+const memoStore = new WeakMap();
+// =============================================================================
+// Registration
+// =============================================================================
+export function registerHtmxExtension() {
+    if (typeof window === "undefined" || !window.htmx)
+        return;
+    window.htmx.defineExtension("litestar", {
+        onEvent(name, evt) {
+            if (name === "htmx:configRequest") {
+                const token = getCsrfToken();
+                if (token)
+                    evt.detail.headers["X-CSRF-Token"] = token;
+            }
+            return true;
+        },
+        transformResponse(text, xhr) {
+            if (xhr.getResponseHeader("content-type")?.includes("application/json")) {
+                const d = document.createElement("div");
+                d.textContent = text;
+                return d.innerHTML;
+            }
+            return text;
+        },
+        isInlineSwap: (s) => s === "json",
+        handleSwap(style, target, frag) {
+            if (style === "json") {
+                try {
+                    swapJson(target, JSON.parse(frag.textContent ?? ""));
+                }
+                catch (e) {
+                    target.innerHTML = `<div style="color:red;padding:1rem">${e}</div>`;
+                }
+                return [target];
+            }
+            return [];
+        },
+    });
+    if (DEBUG)
+        console.log("[litestar] htmx extension registered");
+}
+// =============================================================================
+// Note: hx-route functionality removed - use generated routes directly
+// Import route from your generated routes.ts file instead:
+//   import { route } from '@/generated/routes'
+//   element.setAttribute('hx-get', route('my_route', { id: 123 }))
+// =============================================================================
+// =============================================================================
+// JSON Swap Entry Point
+// =============================================================================
+export function swapJson(el, data) {
+    swap(el, rootCtx(data));
+}
+// =============================================================================
+// Core Swap Logic
+// =============================================================================
+function swap(node, ctx, end, parse = false) {
+    // Text nodes: interpolate ${expr}
+    if (node.nodeType === 3) {
+        const g = memo(node, "t", () => {
+            const t = node.textContent ?? "";
+            return compileTextExpr(t);
+        });
+        if (!g)
+            return null;
+        if (!parse)
+            node.textContent = String(g(ctx) ?? "");
+        return node;
+    }
+    // Elements
+    if (node.nodeType === 1) {
+        const el = node;
+        // Template: structural directives
+        if (el.nodeName === "TEMPLATE") {
+            return forDir(el, ctx, end, parse) ?? ifDir(el, ctx, end, parse);
+        }
+        // Process attribute directives
+        let c = ctx;
+        const handlers = memo(el, "a", () => {
+            const h = [];
+            for (const attr of Array.from(el.attributes)) {
+                const d = directives.find((x) => x.match(attr));
+                if (d) {
+                    const handler = d.create(el, attr);
+                    if (handler)
+                        h.push(handler);
+                }
+            }
+            return h;
+        });
+        for (const h of handlers) {
+            if (!parse && c) {
+                const r = h(c, el);
+                if (r !== undefined)
+                    c = r;
+            }
+            if (!c)
+                break;
+        }
+        if (c === false)
+            return el;
+        if (!c)
+            return null;
+        // Recurse children
+        swapKids(el.firstChild, undefined, c, parse);
+        return el;
+    }
+    return null;
+}
+function swapKids(start, end, ctx, parse = false) {
+    let current = start;
+    while (current && current !== end) {
+        const r = swap(current, ctx, end, parse);
+        current = (r ?? current).nextSibling;
+    }
+}
+const directives = [
+    // :attr="expr" - attribute binding
+    {
+        match: (a) => a.name.startsWith(":"),
+        create(_el, a) {
+            const name = a.name.slice(1);
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx, el) => {
+                const v = g(ctx);
+                if (name === "class" && typeof v === "object" && v) {
+                    for (const [k, on] of Object.entries(v))
+                        el.classList.toggle(k, Boolean(on));
+                }
+                else if (v == null || v === false) {
+                    el.removeAttribute(name);
+                }
+                else {
+                    el.setAttribute(name, v === true ? "" : String(v));
+                }
+            };
+        },
+    },
+    // @event="expr" - event binding
+    {
+        match: (a) => a.name.startsWith("@"),
+        create(_el, a) {
+            const name = a.name.slice(1);
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            let bound = false;
+            return (ctx, el) => {
+                if (!bound) {
+                    bound = true;
+                    el.addEventListener(name, (e) => g({ ...ctx, $event: e }));
+                }
+            };
+        },
+    },
+    // ls-scope="expr" - change context
+    {
+        match: (a) => a.name === "ls-scope",
+        create(_, a) {
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx) => {
+                const d = g(ctx);
+                return d ? childCtx(ctx, d) : false;
+            };
+        },
+    },
+    // ls-text="expr" - text content
+    {
+        match: (a) => a.name === "ls-text",
+        create(_, a) {
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx, el) => {
+                el.textContent = String(g(ctx) ?? "");
+            };
+        },
+    },
+    // ls-html="expr" - innerHTML (use carefully)
+    {
+        match: (a) => a.name === "ls-html",
+        create(_, a) {
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx, el) => {
+                el.innerHTML = String(g(ctx) ?? "");
+            };
+        },
+    },
+    // ls-show/ls-hide
+    {
+        match: (a) => a.name === "ls-show",
+        create(_, a) {
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx, el) => {
+                ;
+                el.style.display = g(ctx) ? "" : "none";
+            };
+        },
+    },
+    {
+        match: (a) => a.name === "ls-hide",
+        create(_, a) {
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx, el) => {
+                ;
+                el.style.display = g(ctx) ? "none" : "";
+            };
+        },
+    },
+    // name attr on inputs - auto-bind from context
+    {
+        match: (a) => a.name === "name",
+        create(el, a) {
+            if (!(el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement))
+                return null;
+            const key = a.value;
+            return (ctx, el) => {
+                const v = ctx[key];
+                if (v === undefined)
+                    return;
+                const inp = el;
+                if (inp.type === "checkbox")
+                    inp.checked = Boolean(v);
+                else if (inp.type === "radio")
+                    inp.checked = v === inp.value;
+                else
+                    inp.value = String(v ?? "");
+            };
+        },
+    },
+];
+// =============================================================================
+// Structural: ls-for
+// =============================================================================
+function forDir(tpl, ctx, _parentEnd, parse = false) {
+    const raw = tpl.getAttribute("ls-for") ?? tpl.getAttribute("ls-each");
+    if (!raw)
+        return null;
+    preparseTpl(tpl);
+    if (parse)
+        return tpl;
+    // Parse "item in items" or just "items"
+    const m = raw.match(/^\s*(\w+)\s+in\s+(.+)$/);
+    const [alias, listExpr] = m ? [m[1], m[2]] : [null, raw];
+    const g = memo(tpl, "g", () => expr(listExpr));
+    if (!g)
+        return null;
+    const items = toList(g(ctx), tpl, ctx, alias);
+    const end = memo(tpl, "end", () => insertComment(tpl, "/ls-for"));
+    const old = memo(tpl, "list", () => collectComments(tpl, end));
+    let i = 0;
+    for (; i < items.length; i++) {
+        const [key, item] = items[i];
+        const c = childCtx(ctx, item, i, key);
+        if (alias)
+            c[alias] = item;
+        if (i < old.length && old[i][0] === key) {
+            // Same key: update in place
+            swapKids(old[i][1].nextSibling, old[i + 1]?.[1] ?? end, c);
+        }
+        else {
+            // Insert new
+            const clone = tpl.content.cloneNode(true);
+            const comment = document.createComment(key);
+            const ref = old[i]?.[1] ?? end;
+            ref.parentNode?.insertBefore(comment, ref);
+            ref.parentNode?.insertBefore(clone, ref);
+            swapKids(comment.nextSibling, ref, c);
+            // Remove old if exists
+            if (i < old.length) {
+                removeBetween(old[i][1], old[i + 1]?.[1] ?? end);
+                old[i][1].remove();
+            }
+            old[i] = [key, comment];
+        }
+    }
+    // Remove excess
+    while (old.length > items.length) {
+        const popped = old.pop();
+        if (!popped)
+            break;
+        const [, c] = popped;
+        removeBetween(c, old[old.length]?.[1] ?? end);
+        c.remove();
+    }
+    return end;
+}
+// =============================================================================
+// Structural: ls-if
+// =============================================================================
+function ifDir(tpl, ctx, _parentEnd, parse = false) {
+    const raw = tpl.getAttribute("ls-if");
+    if (!raw)
+        return null;
+    preparseTpl(tpl);
+    // Find else template
+    const elseTpl = tpl.nextElementSibling?.nodeName === "TEMPLATE" && tpl.nextElementSibling.hasAttribute("ls-else") ? tpl.nextElementSibling : null;
+    if (elseTpl)
+        preparseTpl(elseTpl);
+    if (parse)
+        return elseTpl ?? tpl;
+    const g = memo(tpl, "g", () => expr(raw));
+    const anchor = memo(tpl, "anchor", () => insertComment(tpl, ""));
+    const end = memo(tpl, "end", () => insertComment(anchor, "/ls-if"));
+    const show = g?.(ctx);
+    if (show) {
+        if (anchor.data !== "if") {
+            anchor.data = "if";
+            removeBetween(anchor.nextSibling, end);
+            end.parentNode?.insertBefore(tpl.content.cloneNode(true), end);
+        }
+        swapKids(anchor.nextSibling, end, ctx);
+    }
+    else if (elseTpl) {
+        if (anchor.data !== "else") {
+            anchor.data = "else";
+            removeBetween(anchor.nextSibling, end);
+            end.parentNode?.insertBefore(elseTpl.content.cloneNode(true), end);
+        }
+        swapKids(anchor.nextSibling, end, ctx);
+    }
+    else {
+        anchor.data = "";
+        removeBetween(anchor.nextSibling, end);
+    }
+    return end;
+}
+// =============================================================================
+// Context
+// =============================================================================
+function rootCtx(data) {
+    const ctx = {
+        $data: data,
+        // Note: route and navigate are optional - users can provide their own
+        // by importing from their generated routes.ts file
+    };
+    if (data && typeof data === "object")
+        Object.setPrototypeOf(ctx, data);
+    return ctx;
+}
+function childCtx(parent, data, index, key) {
+    const ctx = Object.create(data && typeof data === "object" ? data : null);
+    ctx.$data = data;
+    ctx.$parent = parent;
+    ctx.$index = index;
+    ctx.$key = key;
+    ctx.route = parent.route;
+    ctx.navigate = parent.navigate;
+    return ctx;
+}
+// =============================================================================
+// Expression Compiler
+// =============================================================================
+function expr(s) {
+    if (!s)
+        return null;
+    const cached = cache.get(s);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const fn = new Function("ctx", `with(ctx){return(${s})}`);
+        cache.set(s, fn);
+        return fn;
+    }
+    catch {
+        cache.set(s, null);
+        return null;
+    }
+}
+/** Compile text with ${expr} interpolation - escapes backticks and backslashes */
+function compileTextExpr(t) {
+    if (!t.includes("${"))
+        return null;
+    // Escape backticks and backslashes for safe template literal compilation
+    const escaped = t.replace(/[`\\]/g, "\\$&");
+    return expr(`\`${escaped}\``);
+}
+// =============================================================================
+// Utilities
+// =============================================================================
+function memo(node, key, fn) {
+    let store = memoStore.get(node);
+    if (!store) {
+        store = {};
+        memoStore.set(node, store);
+    }
+    if (!(key in store)) {
+        store[key] = fn();
+    }
+    return store[key];
+}
+function preparseTpl(t) {
+    memo(t, "p", () => {
+        swapKids(t.content.firstChild, undefined, {}, true);
+        return true;
+    });
+}
+function toList(items, tpl, ctx, alias) {
+    const keyAttr = tpl.getAttribute("ls-key");
+    const keyFn = keyAttr ? expr(keyAttr) : null;
+    if (Array.isArray(items)) {
+        return items.map((item, i) => {
+            if (!keyFn)
+                return [String(i), item];
+            // Create a child context with the alias so key expressions like "item.id" work
+            const keyCtx = childCtx(ctx, item, i);
+            if (alias)
+                keyCtx[alias] = item;
+            return [String(keyFn(keyCtx)), item];
+        });
+    }
+    if (items && typeof items === "object") {
+        return Object.entries(items);
+    }
+    return [];
+}
+function insertComment(after, text) {
+    const c = document.createComment(text);
+    after.parentNode?.insertBefore(c, after.nextSibling);
+    return c;
+}
+function collectComments(tpl, end) {
+    const list = [];
+    let n = tpl.nextSibling;
+    while (n && n !== end) {
+        if (n.nodeType === 8 && !n.data.startsWith("/")) {
+            list.push([n.data, n]);
+        }
+        n = n.nextSibling;
+    }
+    return list;
+}
+function removeBetween(start, end) {
+    let current = start;
+    while (current && current !== end) {
+        const next = current.nextSibling;
+        current.parentNode?.removeChild(current);
+        current = next;
+    }
+}
+// =============================================================================
+// Public API
+// =============================================================================
+export function setDebug(_on) {
+    // Debug flag is const, this is a no-op placeholder
+}
+export function addDirective(dir) {
+    directives.push(dir);
+}
+// Auto-register
+if (typeof window !== "undefined" && window.htmx)
+    registerHtmxExtension();

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

@@ -6,10 +6,10 @@
  *
  * @example
  * ```ts
- * import { route, getCsrfToken, csrfFetch } from 'litestar-vite-plugin/helpers'
+ * import { getCsrfToken, csrfFetch } from 'litestar-vite-plugin/helpers'
  *
- * // Generate a URL for a named route
- * const url = route('user:detail', { user_id: 123 })
+ * // Get CSRF token
+ * const token = getCsrfToken()
  *
  * // Make a fetch request with CSRF token
  * await csrfFetch('/api/submit', {
@@ -18,7 +18,15 @@
  * })
  * ```
  *
+ * For type-safe routing, import from your generated routes file:
+ * ```ts
+ * import { route, routes, type RouteName } from '@/generated/routes'
+ *
+ * // Type-safe URL generation
+ * const url = route('user_detail', { user_id: 123 })  // Compile-time checked!
+ * ```
+ *
  * @module
  */
 export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
-export { currentRoute, getRelativeUrlPath, getRoutes, isCurrentRoute, isRoute, LITESTAR, type LitestarHelpers, type RouteDefinition, type RoutesMap, route, toRoute, } from "./routes.js";
+export { addDirective, registerHtmxExtension, setDebug as setHtmxDebug, swapJson } from "./htmx.js";