litestar-vite-plugin 0.26.1 → 0.28.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.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);

package/dist/js/install-hint.d.ts

@@ -3,7 +3,7 @@
  * Priority: LITESTAR_VITE_RUNTIME env > .litestar.json executor > lockfile detection > 'node'
  */
 export declare function detectExecutor(): string;
-export declare function resolveInstallHint(pkg?: string): string;
+export declare function resolveInstallHint(pkg?: string | readonly string[]): string;
 /**
  * Resolves the package executor command based on runtime.
  * Priority: explicit executor > .litestar.json > LITESTAR_VITE_RUNTIME env > lockfile detection > 'npx'
@@ -26,6 +26,13 @@ export interface PackageExecutorArgvOptions {
      * separate from the command binary, e.g. npm exec --package.
      */
     packageSpec?: string;
+    /**
+     * Additional package specs required in the temporary execution environment.
+     *
+     * npm, pnpm, and Yarn support this. Bun and Deno do not currently expose a
+     * reliable equivalent, so their resolver returns no fallback.
+     */
+    additionalPackageSpecs?: readonly string[];
     /** Binary command exposed by packageSpec. */
     binName?: string;
 }

package/dist/js/install-hint.js

@@ -32,21 +32,23 @@ function detectExecutor() {
 }
 function resolveInstallHint(pkg = "@hey-api/openapi-ts") {
   const runtime = detectExecutor();
+  const packageSpecs = typeof pkg === "string" ? [pkg] : pkg;
+  const packageArgs = packageSpecs.join(" ");
   switch (runtime) {
     case "bun":
-      return `bun add -d ${pkg}`;
+      return `bun add -d ${packageArgs}`;
     case "deno":
-      return `deno add -d npm:${pkg}`;
+      return `deno add -d ${packageSpecs.map((packageSpec) => `npm:${packageSpec}`).join(" ")}`;
     case "pnpm":
-      return `pnpm add -D ${pkg}`;
+      return `pnpm add -D ${packageArgs}`;
     case "yarn":
-      return `yarn add -D ${pkg}`;
+      return `yarn add -D ${packageArgs}`;
   }
   const envInstall = process.env.LITESTAR_VITE_INSTALL_CMD?.trim();
   if (envInstall) {
-    return `${envInstall} -D ${pkg}`;
+    return `${envInstall} -D ${packageArgs}`;
   }
-  return `npm install -D ${pkg}`;
+  return `npm install -D ${packageArgs}`;
 }
 function resolvePackageExecutor(pkg, executor) {
   const runtime = executor || detectExecutor();
@@ -79,19 +81,29 @@ function resolveDenoPackageSpec(packageSpec, binName) {
 }
 function resolvePackageExecutorArgv(args, executor, options = {}) {
   const runtime = executor || detectExecutor();
-  const { packageSpec, binName } = options;
+  const { packageSpec, additionalPackageSpecs = [], binName } = options;
+  const packageSpecs = packageSpec ? [packageSpec, ...additionalPackageSpecs] : [];
+  const requiresMultiplePackages = packageSpecs.length > 1;
   switch (runtime) {
     case "bun":
+      if (requiresMultiplePackages) return [];
       return ["bunx", ...packageSpec ? [packageSpec, ...args] : args];
     case "deno":
+      if (requiresMultiplePackages) return [];
       return ["deno", "run", "-A", ...packageSpec ? [`npm:${resolveDenoPackageSpec(packageSpec, binName)}`, ...args] : args];
     case "pnpm":
+      if (requiresMultiplePackages && binName) {
+        return ["pnpm", "dlx", ...packageSpecs.map((spec) => `--package=${spec}`), binName, ...args];
+      }
       return ["pnpm", "dlx", ...packageSpec ? [packageSpec, ...args] : args];
     case "yarn":
+      if (requiresMultiplePackages && binName) {
+        return ["yarn", "dlx", ...packageSpecs.flatMap((spec) => ["-p", spec]), binName, ...args];
+      }
       return ["yarn", "dlx", ...packageSpec ? [packageSpec, ...args] : args];
     default:
       if (packageSpec && binName) {
-        return ["npm", "exec", "--yes", "--package", packageSpec, "--", binName, ...args];
+        return ["npm", "exec", "--yes", ...packageSpecs.flatMap((spec) => ["--package", spec]), "--", binName, ...args];
       }
       return ["npx", ...args];
   }