litestar-vite-plugin 0.27.0 → 0.29.0

package/dist/js/helpers/stream-element.js

@@ -0,0 +1,229 @@
+/**
+ * Declarative lifecycle binding for JSON WebSocket and SSE streams.
+ *
+ * This element replaces `htmx-ext-ws` and `htmx-ext-sse` for JSON streams.
+ * Do not layer both reconnect implementations on the same endpoint.
+ *
+ * @example
+ * ```html
+ * <litestar-stream url="/events" transport="sse" swap="json">
+ *   <template ls-for="item in $data.items"><p>${item}</p></template>
+ * </litestar-stream>
+ * ```
+ *
+ * @module
+ */
+import { swapJson } from "./htmx.js";
+import { createQueueEventStream } from "./queues.js";
+import { createEventStream } from "./stream.js";
+const HTMLElementBase = (typeof HTMLElement === "undefined" ? class {
+} : HTMLElement);
+export class LitestarStreamElement extends HTMLElementBase {
+    static observedAttributes = ["url", "transport", "sse-events", "preset", "swap", "disabled"];
+    stream = null;
+    _buildUrl;
+    _onEvent;
+    _onGap;
+    _onHealthChange;
+    _onReconnect;
+    _shouldReconnect;
+    _isHeartbeat;
+    _getEventKey;
+    _getSequence;
+    _parseFrame;
+    _WebSocketCtor;
+    _EventSourceCtor;
+    constructor() {
+        super();
+        for (const property of [
+            "buildUrl",
+            "onEvent",
+            "onGap",
+            "onHealthChange",
+            "onReconnect",
+            "shouldReconnect",
+            "isHeartbeat",
+            "getEventKey",
+            "getSequence",
+            "parseFrame",
+            "WebSocketCtor",
+            "EventSourceCtor",
+        ]) {
+            this.upgradeProperty(property);
+        }
+    }
+    get buildUrl() {
+        return this._buildUrl;
+    }
+    set buildUrl(value) {
+        this._buildUrl = value;
+        this.restart();
+    }
+    get onEvent() {
+        return this._onEvent;
+    }
+    set onEvent(value) {
+        this._onEvent = value;
+    }
+    get onGap() {
+        return this._onGap;
+    }
+    set onGap(value) {
+        this._onGap = value;
+    }
+    get onHealthChange() {
+        return this._onHealthChange;
+    }
+    set onHealthChange(value) {
+        this._onHealthChange = value;
+    }
+    get onReconnect() {
+        return this._onReconnect;
+    }
+    set onReconnect(value) {
+        this._onReconnect = value;
+    }
+    get shouldReconnect() {
+        return this._shouldReconnect;
+    }
+    set shouldReconnect(value) {
+        this._shouldReconnect = value;
+    }
+    get isHeartbeat() {
+        return this._isHeartbeat;
+    }
+    set isHeartbeat(value) {
+        this._isHeartbeat = value;
+    }
+    get getEventKey() {
+        return this._getEventKey;
+    }
+    set getEventKey(value) {
+        this._getEventKey = value;
+    }
+    get getSequence() {
+        return this._getSequence;
+    }
+    set getSequence(value) {
+        this._getSequence = value;
+    }
+    get parseFrame() {
+        return this._parseFrame;
+    }
+    set parseFrame(value) {
+        this._parseFrame = value;
+    }
+    get WebSocketCtor() {
+        return this._WebSocketCtor;
+    }
+    set WebSocketCtor(value) {
+        this._WebSocketCtor = value;
+    }
+    get EventSourceCtor() {
+        return this._EventSourceCtor;
+    }
+    set EventSourceCtor(value) {
+        this._EventSourceCtor = value;
+    }
+    get healthy() {
+        return this.stream?.healthy ?? false;
+    }
+    connectedCallback() {
+        this.start();
+    }
+    disconnectedCallback() {
+        this.stop();
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (oldValue === newValue || name === "swap") {
+            return;
+        }
+        this.restart();
+    }
+    upgradeProperty(property) {
+        if (!Object.prototype.hasOwnProperty.call(this, property)) {
+            return;
+        }
+        const value = this[property];
+        delete this[property];
+        this[property] = value;
+    }
+    start() {
+        if (!this.isConnected || this.hasAttribute("disabled") || this.stream !== null) {
+            return;
+        }
+        const url = this.getAttribute("url");
+        if (this._buildUrl === undefined && url === null) {
+            return;
+        }
+        const transport = this.getAttribute("transport") === "sse" ? "sse" : "websocket";
+        const sseEvents = this.getAttribute("sse-events")
+            ?.split(",")
+            .map((event) => event.trim())
+            .filter(Boolean);
+        const config = {
+            EventSourceCtor: this._EventSourceCtor,
+            WebSocketCtor: this._WebSocketCtor,
+            getEventKey: this._getEventKey,
+            getSequence: this._getSequence,
+            isHeartbeat: this._isHeartbeat,
+            onClose: () => this.dispatchStreamEvent("litestar:stream-close", {}),
+            onEvent: (frame) => {
+                this._onEvent?.(frame);
+                this.dispatchStreamEvent("litestar:stream-event", frame);
+                if (this.getAttribute("swap") === "json") {
+                    swapJson(this, frame);
+                }
+            },
+            onGap: (gap) => {
+                this._onGap?.(gap);
+                this.dispatchStreamEvent("litestar:stream-gap", gap);
+            },
+            onHealthChange: (healthy) => {
+                this._onHealthChange?.(healthy);
+                this.dispatchStreamEvent("litestar:stream-health", { healthy });
+            },
+            onOpen: (resolvedUrl) => this.dispatchStreamEvent("litestar:stream-open", { url: resolvedUrl }),
+            onReconnect: () => this._onReconnect?.(),
+            parseFrame: this._parseFrame,
+            shouldReconnect: this._shouldReconnect,
+            sseEvents,
+            transport: transport,
+        };
+        const endpoint = this._buildUrl === undefined ? { url: url } : { buildUrl: this._buildUrl };
+        this.stream = this.getAttribute("preset") === "queues" ? createQueueEventStream({ ...config, ...endpoint }) : createEventStream({ ...config, ...endpoint });
+        this.stream.connect();
+    }
+    stop() {
+        const stream = this.stream;
+        this.stream = null;
+        stream?.dispose();
+    }
+    restart() {
+        if (!this.isConnected) {
+            return;
+        }
+        this.stop();
+        this.start();
+    }
+    dispatchStreamEvent(type, detail) {
+        this.dispatchEvent(new CustomEvent(type, { bubbles: true, composed: false, detail }));
+    }
+}
+/**
+ * Register the declarative stream element.
+ *
+ * @param options - Optional custom tag name.
+ */
+export function defineStreamElement(options = {}) {
+    if (typeof window === "undefined" || typeof customElements === "undefined") {
+        return;
+    }
+    const tagName = options.tagName ?? "litestar-stream";
+    if (customElements.get(tagName) !== undefined) {
+        return;
+    }
+    const ElementClass = tagName === "litestar-stream" ? LitestarStreamElement : class extends LitestarStreamElement {
+    };
+    customElements.define(tagName, ElementClass);
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Resilient WebSocket and SSE helpers for Litestar event streams.
+ *
+ * @example
+ * ```ts
+ * import { createEventStream } from "litestar-vite-plugin/helpers"
+ *
+ * const stream = createEventStream({
+ *   url: "/events",
+ *   onEvent: (event) => console.log(event),
+ * })
+ *
+ * stream.connect()
+ * ```
+ *
+ * @module
+ */
+export interface StreamGap {
+    stream: string;
+    from: number;
+    to: number;
+    missing: number;
+}
+export type EventStreamTransport = "websocket" | "sse";
+export type StreamUrl = string | URL | (() => string | URL);
+export interface EventStreamConfig<TFrame = unknown> {
+    transport?: "websocket" | "sse";
+    sseEvents?: readonly string[];
+    onEvent: (frame: TFrame) => void;
+    onOpen?: (url: string) => void;
+    onClose?: () => void;
+    onHealthChange?: (healthy: boolean) => void;
+    onReconnect?: () => void;
+    onGap?: (gap: StreamGap) => void;
+    shouldReconnect?: (closeCode: number) => boolean;
+    isHeartbeat?: (frame: TFrame) => boolean;
+    getEventKey?: (frame: TFrame) => string | undefined;
+    getSequence?: (frame: TFrame) => {
+        stream: string;
+        value: number;
+    } | undefined;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    dedupWindow?: number;
+    parseFrame?: (data: string) => TFrame;
+    WebSocketCtor?: typeof WebSocket;
+    EventSourceCtor?: typeof EventSource;
+}
+export type EventStreamOptions<TFrame = unknown> = EventStreamConfig<TFrame> & ({
+    url: StreamUrl;
+    buildUrl?: never;
+} | {
+    url?: never;
+    buildUrl: () => string | URL;
+});
+export interface EventStream {
+    connect(): void;
+    dispose(): void;
+    readonly healthy: boolean;
+}
+/**
+ * Resolve a stream endpoint against the browser origin.
+ *
+ * @param value - Absolute or same-origin relative endpoint.
+ * @param transport - Transport whose URL protocol should be used.
+ * @param baseUrl - Resolution base. Defaults to the current browser location.
+ * @returns An absolute transport URL.
+ */
+export declare function resolveStreamUrl(value: string | URL, transport: EventStreamTransport, baseUrl?: string | URL): string;
+/**
+ * Create a reconnecting, transport-agnostic Litestar event stream.
+ *
+ * @param options - Stream transport, lifecycle, and frame-processing options.
+ * @returns A disposable stream that connects only when `connect()` is called.
+ */
+export declare function createEventStream<TFrame = unknown>(options: EventStreamOptions<TFrame>): EventStream;

package/dist/js/helpers/stream.js

@@ -0,0 +1,242 @@
+/**
+ * Resilient WebSocket and SSE helpers for Litestar event streams.
+ *
+ * @example
+ * ```ts
+ * import { createEventStream } from "litestar-vite-plugin/helpers"
+ *
+ * const stream = createEventStream({
+ *   url: "/events",
+ *   onEvent: (event) => console.log(event),
+ * })
+ *
+ * stream.connect()
+ * ```
+ *
+ * @module
+ */
+const DEFAULT_BASE_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 10_000;
+const DEFAULT_DEDUP_WINDOW = 1024;
+const DEFAULT_SSE_EVENTS = ["message"];
+function defaultParseFrame(data) {
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return data;
+    }
+}
+/**
+ * Resolve a stream endpoint against the browser origin.
+ *
+ * @param value - Absolute or same-origin relative endpoint.
+ * @param transport - Transport whose URL protocol should be used.
+ * @param baseUrl - Resolution base. Defaults to the current browser location.
+ * @returns An absolute transport URL.
+ */
+export function resolveStreamUrl(value, transport, baseUrl = window.location.href) {
+    const resolved = new URL(value, baseUrl);
+    if (transport === "websocket") {
+        if (resolved.protocol === "http:") {
+            resolved.protocol = "ws:";
+        }
+        else if (resolved.protocol === "https:") {
+            resolved.protocol = "wss:";
+        }
+    }
+    else if (resolved.protocol === "ws:") {
+        resolved.protocol = "http:";
+    }
+    else if (resolved.protocol === "wss:") {
+        resolved.protocol = "https:";
+    }
+    return resolved.toString();
+}
+/**
+ * Create a reconnecting, transport-agnostic Litestar event stream.
+ *
+ * @param options - Stream transport, lifecycle, and frame-processing options.
+ * @returns A disposable stream that connects only when `connect()` is called.
+ */
+export function createEventStream(options) {
+    const { transport = "websocket", sseEvents = DEFAULT_SSE_EVENTS, onEvent, onOpen, onClose, onHealthChange, onReconnect, onGap, shouldReconnect = (closeCode) => closeCode !== 1000, isHeartbeat = () => false, getEventKey = () => undefined, getSequence = () => undefined, baseDelayMs = DEFAULT_BASE_DELAY_MS, maxDelayMs = DEFAULT_MAX_DELAY_MS, dedupWindow = DEFAULT_DEDUP_WINDOW, parseFrame = defaultParseFrame, } = options;
+    let connection = null;
+    let attempt = 0;
+    let timer = null;
+    let disposed = false;
+    let lastHealthy = null;
+    let hasOpened = false;
+    const seenKeys = [];
+    const seenKeySet = new Set();
+    const sequenceByStream = new Map();
+    function emitHealth(healthy) {
+        if (lastHealthy === healthy) {
+            return;
+        }
+        lastHealthy = healthy;
+        onHealthChange?.(healthy);
+    }
+    function clearTimer() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function scheduleReconnect() {
+        clearTimer();
+        attempt += 1;
+        const ceiling = Math.min(baseDelayMs * 2 ** (attempt - 1), maxDelayMs);
+        const delay = Math.random() * ceiling;
+        timer = setTimeout(() => {
+            timer = null;
+            if (!disposed) {
+                open();
+            }
+        }, delay);
+    }
+    function handleOpen(url) {
+        attempt = 0;
+        clearTimer();
+        emitHealth(true);
+        onOpen?.(url);
+        if (hasOpened) {
+            onReconnect?.();
+        }
+        else {
+            hasOpened = true;
+        }
+    }
+    function handleMessage(event) {
+        const frame = parseFrame(String(event.data));
+        if (isHeartbeat(frame)) {
+            return;
+        }
+        const eventKey = getEventKey(frame);
+        if (eventKey !== undefined && dedupWindow > 0) {
+            if (seenKeySet.has(eventKey)) {
+                return;
+            }
+            seenKeys.push(eventKey);
+            seenKeySet.add(eventKey);
+            if (seenKeys.length > dedupWindow) {
+                const evicted = seenKeys.shift();
+                if (evicted !== undefined) {
+                    seenKeySet.delete(evicted);
+                }
+            }
+        }
+        const sequence = getSequence(frame);
+        if (sequence !== undefined && Number.isFinite(sequence.value)) {
+            const last = sequenceByStream.get(sequence.stream);
+            if (last === undefined) {
+                sequenceByStream.set(sequence.stream, sequence.value);
+            }
+            else if (sequence.value > last) {
+                sequenceByStream.set(sequence.stream, sequence.value);
+                if (sequence.value > last + 1) {
+                    onGap?.({
+                        stream: sequence.stream,
+                        from: last,
+                        to: sequence.value,
+                        missing: sequence.value - last - 1,
+                    });
+                }
+            }
+        }
+        onEvent(frame);
+    }
+    function buildConnectionUrl() {
+        const value = options.buildUrl === undefined ? options.url : options.buildUrl();
+        const endpoint = typeof value === "function" ? value() : value;
+        return resolveStreamUrl(endpoint, transport);
+    }
+    function openWebSocket() {
+        const WebSocketCtor = options.WebSocketCtor ?? window.WebSocket;
+        const url = buildConnectionUrl();
+        const next = new WebSocketCtor(url);
+        connection = next;
+        next.addEventListener("open", () => {
+            handleOpen(url);
+        });
+        next.addEventListener("message", (event) => {
+            handleMessage(event);
+        });
+        next.addEventListener("close", (event) => {
+            if (connection !== next) {
+                return;
+            }
+            connection = null;
+            onClose?.();
+            emitHealth(false);
+            if (disposed || !shouldReconnect(event.code)) {
+                return;
+            }
+            scheduleReconnect();
+        });
+        next.addEventListener("error", () => {
+            emitHealth(false);
+        });
+    }
+    function openEventSource() {
+        const EventSourceCtor = options.EventSourceCtor ?? window.EventSource;
+        const url = buildConnectionUrl();
+        const next = new EventSourceCtor(url);
+        connection = next;
+        next.addEventListener("open", () => {
+            handleOpen(url);
+        });
+        for (const eventType of sseEvents) {
+            next.addEventListener(eventType, (event) => {
+                handleMessage(event);
+            });
+        }
+        next.addEventListener("error", () => {
+            if (connection !== next) {
+                return;
+            }
+            connection = null;
+            next.close();
+            onClose?.();
+            emitHealth(false);
+            if (disposed || !shouldReconnect(1006)) {
+                return;
+            }
+            scheduleReconnect();
+        });
+    }
+    function open() {
+        if (disposed || typeof window === "undefined") {
+            return;
+        }
+        if (transport === "sse") {
+            openEventSource();
+            return;
+        }
+        openWebSocket();
+    }
+    return {
+        connect() {
+            if (disposed || typeof window === "undefined") {
+                return;
+            }
+            attempt = 0;
+            clearTimer();
+            open();
+        },
+        dispose() {
+            disposed = true;
+            clearTimer();
+            const current = connection;
+            connection = null;
+            if (current !== null) {
+                onClose?.();
+                emitHealth(false);
+                current.close();
+            }
+        },
+        get healthy() {
+            return lastHealthy ?? false;
+        },
+    };
+}

package/dist/js/index.d.ts

@@ -1,114 +1,12 @@
 import { type Config as FullReloadConfig } from "vite-plugin-full-reload";
+import { type TypesConfigShape } from "./shared/typegen-plugin.js";
 /**
  * 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
+ * Alias of the shared {@link TypesConfigShape}, which every framework integration also
+ * re-exports, so the `types` option is identical everywhere. Retained as a named export.
  */
-export interface TypesConfig {
-    /**
-     * Enable type generation.
-     *
-     * @default false
-     */
-    enabled?: boolean;
-    /**
-     * Path to output generated TypeScript types.
-     *
-     * @default 'src/generated'
-     */
-    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 'src/generated/openapi.json'
-     */
-    openapiPath?: string;
-    /**
-     * Path where route metadata is exported by Litestar.
-     * The Vite plugin watches this file for route helper generation.
-     *
-     * @default 'src/generated/routes.json'
-     */
-    routesPath?: string;
-    /**
-     * Optional path for the generated schemas.ts helper file.
-     * Defaults to `${output}/schemas.ts` when not set.
-     */
-    schemasTsPath?: string;
-    /**
-     * Path where Inertia page props metadata is exported by Litestar.
-     * The Vite plugin watches this file for page props type generation.
-     *
-     * @default 'src/generated/inertia-pages.json'
-     */
-    pagePropsPath?: string;
-    /**
-     * Generate Zod schemas in addition to TypeScript types.
-     *
-     * @default false
-     */
-    generateZod?: boolean;
-    /**
-     * Generate a typed SDK client in addition to types.
-     *
-     * @default true
-     */
-    generateSdk?: boolean;
-    /**
-     * Generate typed routes.ts from routes.json metadata.
-     *
-     * Mirrors Python TypeGenConfig.generate_routes.
-     *
-     * @default true
-     */
-    generateRoutes?: boolean;
-    /**
-     * Generate Inertia page props types from inertia-pages.json metadata.
-     *
-     * Mirrors Python TypeGenConfig.generate_page_props.
-     *
-     * @default true
-     */
-    generatePageProps?: boolean;
-    /**
-     * Generate schemas.ts with ergonomic form/response type helpers.
-     *
-     * Creates helper types like FormInput<'api:login'> and FormResponse<'api:login', 201>
-     * that wrap hey-api generated types with cleaner DX.
-     *
-     * @default true
-     */
-    generateSchemas?: boolean;
-    /**
-     * Register route() function globally on window object.
-     *
-     * When true, the generated routes.ts will include code that registers
-     * the type-safe route() function on `window.route`, similar to Laravel's
-     * Ziggy library. This allows using route() without imports.
-     *
-     * @default false
-     */
-    globalRoute?: boolean;
-    /**
-     * Fail Vite when type generation fails.
-     *
-     * Defaults to true during `vite build` and false during `vite serve`.
-     */
-    failOnError?: 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 type TypesConfig = TypesConfigShape;
 export interface PluginConfig {
     /**
      * The path or paths of the entry points to compile.

package/dist/js/index.js

@@ -7,6 +7,7 @@ import fullReload from "vite-plugin-full-reload";
 import { checkBackendAvailability, loadLitestarMeta } from "./litestar-meta.js";
 import { readBridgeConfig } from "./shared/bridge-schema.js";
 import { createLogger } from "./shared/logger.js";
+import { installManagedShutdown } from "./shared/managed-shutdown.js";
 import { resolveLitestarPort } from "./shared/network.js";
 import { resolveDefaultSdkClientPlugin } from "./shared/typegen-core.js";
 import { createLitestarTypeGenPlugin, resolveTypesConfig } from "./shared/typegen-plugin.js";
@@ -320,6 +321,9 @@ function resolveLitestarPlugin(pluginConfig) {
         }
       });
       if (!exitHandlersBound) {
+        installManagedShutdown(server, () => {
+          shuttingDown = true;
+        });
         const clean = () => {
           if (pluginConfig.hotFile && fs.existsSync(pluginConfig.hotFile)) {
             fs.rmSync(pluginConfig.hotFile);