litestar-vite-plugin 0.27.0 → 0.29.0

package/dist/js/helpers/htmx.js

@@ -27,7 +27,8 @@
  *
  * @module
  */
-import { DEFAULT_CSRF_HEADER_NAME, getCsrfToken } from "./csrf.js";
+import { getCsrfHeaderName, getCsrfToken } from "./csrf.js";
+import { compileExpression } from "./expression.js";
 function getHeadersFromConfigRequestEvent(evt) {
     const detail = evt.detail;
     if (!detail || typeof detail !== "object")
@@ -80,12 +81,13 @@ export function registerHtmxExtension() {
         onEvent(name, evt) {
             if (name === "htmx:configRequest") {
                 const token = getCsrfToken();
+                const headerName = getCsrfHeaderName();
                 const headers = getHeadersFromConfigRequestEvent(evt);
                 if (token && headers) {
                     if (headers instanceof Headers)
-                        headers.set(DEFAULT_CSRF_HEADER_NAME, token);
+                        headers.set(headerName, token);
                     else
-                        headers[DEFAULT_CSRF_HEADER_NAME] = token;
+                        headers[headerName] = token;
                 }
             }
             return true;
@@ -194,6 +196,28 @@ function swapKids(start, end, ctx, parse = false) {
         current = (r ?? current).nextSibling;
     }
 }
+function wrapEvent(event) {
+    const eventTarget = event.target;
+    let target = null;
+    if (eventTarget instanceof HTMLInputElement || eventTarget instanceof HTMLSelectElement || eventTarget instanceof HTMLTextAreaElement) {
+        target = Object.freeze({
+            value: eventTarget.value,
+            name: eventTarget.name,
+            checked: eventTarget instanceof HTMLInputElement ? eventTarget.checked : false,
+            id: eventTarget.id,
+            type: eventTarget instanceof HTMLInputElement ? eventTarget.type : "",
+        });
+    }
+    else if (eventTarget instanceof Element) {
+        target = Object.freeze({ value: "", name: "", checked: false, id: eventTarget.id, type: "" });
+    }
+    return Object.freeze({
+        type: event.type,
+        target,
+        preventDefault: () => event.preventDefault(),
+        stopPropagation: () => event.stopPropagation(),
+    });
+}
 const directives = [
     // :attr="expr" - attribute binding
     {
@@ -246,7 +270,7 @@ const directives = [
                     if (!current)
                         return;
                     const eventCtx = Object.create(current);
-                    eventCtx.$event = e;
+                    eventCtx.$event = wrapEvent(e);
                     g(eventCtx);
                 });
             };
@@ -458,131 +482,6 @@ function childCtx(parent, data, index, key) {
 // =============================================================================
 // Expression Compiler
 // =============================================================================
-/** Identifiers that must never appear as standalone words in expressions */
-const BLOCKED_GLOBALS = [
-    "window",
-    "document",
-    "globalThis",
-    "self",
-    "top",
-    "frames",
-    "Function",
-    "eval",
-    "setTimeout",
-    "setInterval",
-    "constructor",
-    "__proto__",
-    "prototype",
-    "import",
-    "require",
-];
-/** Build a single regex: matches any blocked word at a word boundary */
-const BLOCKED_RE = new RegExp(`\\b(${BLOCKED_GLOBALS.join("|")})\\b`);
-/** Strip string literals and template strings before checking for blocked patterns */
-function stripStrings(s) {
-    return s
-        .replace(/`(?:[^`\\]|\\.)*`/g, "") // template literals
-        .replace(/"(?:[^"\\]|\\.)*"/g, "") // double-quoted strings
-        .replace(/'(?:[^'\\]|\\.)*'/g, ""); // single-quoted strings
-}
-function readQuotedLiteral(s, start) {
-    const quote = s[start];
-    if (quote !== "'" && quote !== '"' && quote !== "`")
-        return null;
-    let value = "";
-    for (let i = start + 1; i < s.length; i++) {
-        const ch = s[i];
-        if (ch === "\\") {
-            if (i + 1 >= s.length)
-                return null;
-            const escaped = readEscapedCharacter(s, i + 1);
-            if (!escaped)
-                return null;
-            value += escaped.value;
-            i = escaped.end - 1;
-            continue;
-        }
-        if (quote === "`" && ch === "$" && s[i + 1] === "{") {
-            return null;
-        }
-        if (ch === quote) {
-            return { end: i + 1, value };
-        }
-        value += ch;
-    }
-    return null;
-}
-function readEscapedCharacter(s, start) {
-    const ch = s[start];
-    if (ch === "u") {
-        if (s[start + 1] === "{") {
-            const close = s.indexOf("}", start + 2);
-            if (close === -1)
-                return null;
-            const codePoint = Number.parseInt(s.slice(start + 2, close), 16);
-            return Number.isFinite(codePoint) ? { end: close + 1, value: String.fromCodePoint(codePoint) } : null;
-        }
-        const codePoint = Number.parseInt(s.slice(start + 1, start + 5), 16);
-        return Number.isFinite(codePoint) ? { end: start + 5, value: String.fromCharCode(codePoint) } : null;
-    }
-    if (ch === "x") {
-        const codePoint = Number.parseInt(s.slice(start + 1, start + 3), 16);
-        return Number.isFinite(codePoint) ? { end: start + 3, value: String.fromCharCode(codePoint) } : null;
-    }
-    const escapes = { b: "\b", f: "\f", n: "\n", r: "\r", t: "\t", v: "\v" };
-    return { end: start + 1, value: escapes[ch] ?? ch };
-}
-function skipTrivia(s, start) {
-    let i = start;
-    while (i < s.length) {
-        while (/\s/.test(s[i] ?? ""))
-            i += 1;
-        if (s[i] === "/" && s[i + 1] === "/") {
-            i = s.indexOf("\n", i + 2);
-            if (i === -1)
-                return s.length;
-            continue;
-        }
-        if (s[i] === "/" && s[i + 1] === "*") {
-            const close = s.indexOf("*/", i + 2);
-            if (close === -1)
-                return s.length;
-            i = close + 2;
-            continue;
-        }
-        break;
-    }
-    return i;
-}
-function hasBlockedStringConcatenation(s) {
-    for (let i = 0; i < s.length; i++) {
-        const first = readQuotedLiteral(s, i);
-        if (!first)
-            continue;
-        const parts = [first.value];
-        let cursor = skipTrivia(s, first.end);
-        while (s[cursor] === "+") {
-            const nextStart = skipTrivia(s, cursor + 1);
-            const next = readQuotedLiteral(s, nextStart);
-            if (!next)
-                break;
-            parts.push(next.value);
-            cursor = skipTrivia(s, next.end);
-        }
-        if (parts.length > 1 && BLOCKED_GLOBALS.includes(parts.join(""))) {
-            return true;
-        }
-        i = first.end - 1;
-    }
-    return false;
-}
-function isExpressionSafe(s) {
-    if (hasBlockedStringConcatenation(s)) {
-        return false;
-    }
-    const stripped = stripStrings(s);
-    return !BLOCKED_RE.test(stripped);
-}
 function expr(s) {
     if (!s)
         return null;
@@ -593,22 +492,16 @@ function expr(s) {
         expressionCache.set(s, cached);
         return cached;
     }
-    if (!isExpressionSafe(s)) {
+    const compiled = compileExpression(s);
+    if (!compiled) {
         if (debug)
             console.warn(`[litestar] blocked expression: ${s}`);
         cacheExpression(s, null);
         return null;
     }
-    try {
-        // Expression validated by isExpressionSafe() above — dangerous globals/constructors blocked
-        const fn = new Function("ctx", `with(ctx){return(${s})}`);
-        cacheExpression(s, fn);
-        return fn;
-    }
-    catch {
-        cacheExpression(s, null);
-        return null;
-    }
+    const fn = (context) => compiled(context);
+    cacheExpression(s, fn);
+    return fn;
 }
 /** Compile text with ${expr} interpolation - escapes backticks and backslashes */
 function compileTextExpr(t) {

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

@@ -38,6 +38,10 @@
  *
  * @module
  */
-export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
+export { csrfFetch, csrfHeaders, getCsrfHeaderName, getCsrfToken } from "./csrf.js";
+export { createChannelsStream, type ChannelName, type ChannelsStreamOptions } from "./channels.js";
 export { addDirective, registerHtmxExtension, setDebug as setHtmxDebug, swapJson } from "./htmx.js";
+export { createQueueEventStream, QUEUE_SSE_EVENTS, type QueueEventStreamOptions, type QueueStreamTarget, type QueueStreamValue } from "./queues.js";
 export { createRouteHelpers, currentRoute, isCurrentRoute, isRoute, type RouteDefinition, type RouteDefinitions, type RouteHelpers, toRoute } from "./routes.js";
+export { createEventStream, type EventStream, type EventStreamOptions, type StreamGap } from "./stream.js";
+export { defineStreamElement, LitestarStreamElement, type StreamElementOptions } from "./stream-element.js";

package/dist/js/helpers/index.js

@@ -39,8 +39,16 @@
  * @module
  */
 // CSRF utilities
-export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
+export { csrfFetch, csrfHeaders, getCsrfHeaderName, getCsrfToken } from "./csrf.js";
+// Litestar Channels utilities
+export { createChannelsStream } from "./channels.js";
 // HTMX utilities
 export { addDirective, registerHtmxExtension, setDebug as setHtmxDebug, swapJson } from "./htmx.js";
+// Litestar Queues utilities
+export { createQueueEventStream, QUEUE_SSE_EVENTS } from "./queues.js";
 // Route matching utilities
 export { createRouteHelpers, currentRoute, isCurrentRoute, isRoute, toRoute } from "./routes.js";
+// Realtime stream utilities
+export { createEventStream } from "./stream.js";
+// Declarative realtime stream element
+export { defineStreamElement, LitestarStreamElement } from "./stream-element.js";

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

@@ -0,0 +1,61 @@
+/**
+ * Browser helper for routes generated by Litestar Queues EventStreamConfig.
+ *
+ * @example
+ * ```ts
+ * import { createQueueEventStream } from "litestar-vite-plugin/helpers"
+ *
+ * const stream = createQueueEventStream({
+ *   scope: "task",
+ *   taskId: "01J...",
+ *   onEvent: (event) => console.log(event),
+ * })
+ * stream.connect()
+ * ```
+ *
+ * @module
+ */
+import { type EventStream, type EventStreamConfig, type StreamUrl } from "./stream.js";
+export declare const QUEUE_SSE_EVENTS: readonly ["task.started", "task.progress", "task.log", "task.event", "task.completed", "task.failed", "task.cancelled", "task.claim_lost", "task.stale_failed", "worker.heartbeat", "worker.stale_recovery"];
+export type QueueStreamValue = string | (() => string);
+export type QueueStreamTarget = {
+    scope: "task";
+    taskId: QueueStreamValue;
+} | {
+    scope: "queue";
+    queue: QueueStreamValue;
+} | {
+    scope: "worker";
+    workerId: QueueStreamValue;
+} | {
+    scope: "global";
+} | {
+    scope: "custom";
+    scopeKey: QueueStreamValue;
+};
+type QueueRouteStreamOptions = QueueStreamTarget & {
+    url?: never;
+    buildUrl?: never;
+    basePath?: string;
+};
+type QueueDirectStreamOptions = {
+    url: StreamUrl;
+    buildUrl?: never;
+    basePath?: never;
+} | {
+    url?: never;
+    buildUrl: () => string | URL;
+    basePath?: never;
+};
+export type QueueEventStreamOptions<TFrame = unknown> = EventStreamConfig<TFrame> & (QueueRouteStreamOptions | QueueDirectStreamOptions) & {
+    basePath?: string;
+    transformUrl?: (url: URL) => string | URL;
+};
+/**
+ * Create a stream for routes generated by QueuePlugin EventStreamConfig.
+ *
+ * @param options - Queue target, transport, and stream callbacks.
+ * @returns A disposable stream that connects only when `connect()` is called.
+ */
+export declare function createQueueEventStream<TFrame = unknown>(options: QueueEventStreamOptions<TFrame>): EventStream;
+export {};

package/dist/js/helpers/queues.js

@@ -0,0 +1,117 @@
+/**
+ * Browser helper for routes generated by Litestar Queues EventStreamConfig.
+ *
+ * @example
+ * ```ts
+ * import { createQueueEventStream } from "litestar-vite-plugin/helpers"
+ *
+ * const stream = createQueueEventStream({
+ *   scope: "task",
+ *   taskId: "01J...",
+ *   onEvent: (event) => console.log(event),
+ * })
+ * stream.connect()
+ * ```
+ *
+ * @module
+ */
+import { createEventStream, resolveStreamUrl } from "./stream.js";
+export const QUEUE_SSE_EVENTS = [
+    "task.started",
+    "task.progress",
+    "task.log",
+    "task.event",
+    "task.completed",
+    "task.failed",
+    "task.cancelled",
+    "task.claim_lost",
+    "task.stale_failed",
+    "worker.heartbeat",
+    "worker.stale_recovery",
+];
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : undefined;
+}
+function defaultQueueIsHeartbeat(frame) {
+    return asRecord(frame)?.type === "ping";
+}
+function defaultQueueGetEventKey(frame) {
+    const record = asRecord(frame);
+    const key = record?.eventKey ?? record?.id;
+    return typeof key === "string" ? key : undefined;
+}
+function defaultQueueGetSequence(frame) {
+    const record = asRecord(frame);
+    const sequence = record?.sequence;
+    const taskId = record?.taskId;
+    const attempt = record?.attempt;
+    if (typeof sequence !== "number" || !Number.isFinite(sequence) || typeof taskId !== "string" || (typeof attempt !== "string" && typeof attempt !== "number")) {
+        return undefined;
+    }
+    return { stream: `${taskId}:${attempt}`, value: sequence };
+}
+function resolveValue(value) {
+    return typeof value === "function" ? value() : value;
+}
+function queueRouteSuffix(target) {
+    switch (target.scope) {
+        case "task":
+            return `tasks/${encodeURIComponent(resolveValue(target.taskId))}`;
+        case "queue":
+            return `queues/${encodeURIComponent(resolveValue(target.queue))}`;
+        case "worker":
+            return `workers/${encodeURIComponent(resolveValue(target.workerId))}`;
+        case "global":
+            return "global";
+        case "custom":
+            return `custom/${encodeURIComponent(resolveValue(target.scopeKey))}`;
+    }
+}
+function queueStreamUrl(target, basePath, transport) {
+    const root = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+    const transportPath = transport === "sse" ? "sse/" : "";
+    return new URL(resolveStreamUrl(`${root}/${transportPath}${queueRouteSuffix(target)}`, transport));
+}
+/**
+ * Create a stream for routes generated by QueuePlugin EventStreamConfig.
+ *
+ * @param options - Queue target, transport, and stream callbacks.
+ * @returns A disposable stream that connects only when `connect()` is called.
+ */
+export function createQueueEventStream(options) {
+    const { baseDelayMs, basePath = "/queues/events", dedupWindow, EventSourceCtor, getEventKey = defaultQueueGetEventKey, getSequence = defaultQueueGetSequence, isHeartbeat = defaultQueueIsHeartbeat, maxDelayMs, onEvent, onClose, onGap, onHealthChange, onOpen, onReconnect, parseFrame, shouldReconnect, sseEvents = QUEUE_SSE_EVENTS, transformUrl, transport = "websocket", WebSocketCtor, } = options;
+    return createEventStream({
+        baseDelayMs,
+        buildUrl: () => {
+            let endpoint;
+            if ("buildUrl" in options && options.buildUrl !== undefined) {
+                endpoint = options.buildUrl();
+            }
+            else if ("url" in options && options.url !== undefined) {
+                endpoint = typeof options.url === "function" ? options.url() : options.url;
+            }
+            else {
+                endpoint = queueStreamUrl(options, basePath, transport);
+            }
+            const url = new URL(resolveStreamUrl(endpoint, transport));
+            return transformUrl?.(url) ?? url;
+        },
+        dedupWindow,
+        EventSourceCtor,
+        getEventKey,
+        getSequence,
+        isHeartbeat,
+        maxDelayMs,
+        onEvent,
+        onClose,
+        onGap,
+        onHealthChange,
+        onOpen,
+        onReconnect,
+        parseFrame,
+        shouldReconnect,
+        sseEvents,
+        transport,
+        WebSocketCtor,
+    });
+}

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

@@ -0,0 +1,79 @@
+/**
+ * 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 { type EventStreamConfig } from "./stream.js";
+type StreamCallbackConfig = Pick<EventStreamConfig, "EventSourceCtor" | "WebSocketCtor" | "getEventKey" | "getSequence" | "isHeartbeat" | "onEvent" | "onGap" | "onHealthChange" | "onReconnect" | "parseFrame" | "shouldReconnect">;
+type HTMLElementConstructor = new (...args: never[]) => HTMLElement;
+declare const HTMLElementBase: HTMLElementConstructor;
+export interface StreamElementOptions {
+    tagName?: string;
+}
+export declare class LitestarStreamElement extends HTMLElementBase {
+    static readonly observedAttributes: string[];
+    private stream;
+    private _buildUrl;
+    private _onEvent;
+    private _onGap;
+    private _onHealthChange;
+    private _onReconnect;
+    private _shouldReconnect;
+    private _isHeartbeat;
+    private _getEventKey;
+    private _getSequence;
+    private _parseFrame;
+    private _WebSocketCtor;
+    private _EventSourceCtor;
+    constructor();
+    get buildUrl(): (() => string | URL) | undefined;
+    set buildUrl(value: (() => string | URL) | undefined);
+    get onEvent(): StreamCallbackConfig["onEvent"] | undefined;
+    set onEvent(value: StreamCallbackConfig["onEvent"] | undefined);
+    get onGap(): StreamCallbackConfig["onGap"];
+    set onGap(value: StreamCallbackConfig["onGap"]);
+    get onHealthChange(): StreamCallbackConfig["onHealthChange"];
+    set onHealthChange(value: StreamCallbackConfig["onHealthChange"]);
+    get onReconnect(): StreamCallbackConfig["onReconnect"];
+    set onReconnect(value: StreamCallbackConfig["onReconnect"]);
+    get shouldReconnect(): StreamCallbackConfig["shouldReconnect"];
+    set shouldReconnect(value: StreamCallbackConfig["shouldReconnect"]);
+    get isHeartbeat(): StreamCallbackConfig["isHeartbeat"];
+    set isHeartbeat(value: StreamCallbackConfig["isHeartbeat"]);
+    get getEventKey(): StreamCallbackConfig["getEventKey"];
+    set getEventKey(value: StreamCallbackConfig["getEventKey"]);
+    get getSequence(): StreamCallbackConfig["getSequence"];
+    set getSequence(value: StreamCallbackConfig["getSequence"]);
+    get parseFrame(): StreamCallbackConfig["parseFrame"];
+    set parseFrame(value: StreamCallbackConfig["parseFrame"]);
+    get WebSocketCtor(): StreamCallbackConfig["WebSocketCtor"];
+    set WebSocketCtor(value: StreamCallbackConfig["WebSocketCtor"]);
+    get EventSourceCtor(): StreamCallbackConfig["EventSourceCtor"];
+    set EventSourceCtor(value: StreamCallbackConfig["EventSourceCtor"]);
+    get healthy(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private upgradeProperty;
+    private start;
+    private stop;
+    private restart;
+    private dispatchStreamEvent;
+}
+/**
+ * Register the declarative stream element.
+ *
+ * @param options - Optional custom tag name.
+ */
+export declare function defineStreamElement(options?: StreamElementOptions): void;
+export {};