@jant/core 0.2.12 → 0.2.13

package/src/lib/sse.ts

@@ -1,8 +1,7 @@
 /**
- * Server-Sent Events (SSE) utilities for Datastar
+ * Server-Sent Events (SSE) utilities for Datastar v1.0.0-RC.7
  *
- * Provides helpers for streaming SSE responses that Datastar can consume.
- * Datastar uses SSE for real-time UI updates without page reloads.
+ * Generates SSE events compatible with the Datastar client's expected format.
  *
  * @see https://data-star.dev/
  *
@@ -11,7 +10,8 @@
  * app.post("/api/example", (c) => {
  *   return sse(c, async (stream) => {
  *     await stream.patchSignals({ loading: false });
- *     await stream.patchElements("#result", "<div>Done!</div>");
+ *     await stream.patchElements('<div id="result">Done!</div>');
+ *     await stream.redirect("/success");
  *   });
  * });
  * ```
@@ -20,9 +20,19 @@
 import type { Context } from "hono";
 
 /**
- * Patch modes for DOM updates
+ * Patch modes for DOM element updates
+ *
+ * @see https://data-star.dev/reference/action_plugins/backend/sse
  */
-export type PatchMode = "morph" | "inner" | "outer" | "append" | "prepend" | "remove";
+export type PatchMode =
+  | "outer"
+  | "inner"
+  | "replace"
+  | "prepend"
+  | "append"
+  | "before"
+  | "after"
+  | "remove";
 
 /**
  * SSE stream writer for Datastar events
@@ -32,23 +42,27 @@ export interface SSEStream {
    * Update reactive signals on the client
    *
    * @param signals - Object containing signal values to update
+   * @param options - Optional settings (e.g. onlyIfMissing)
    *
    * @example
    * ```ts
    * await stream.patchSignals({ count: 42, loading: false });
    * ```
    */
-  patchSignals(signals: Record<string, unknown>): Promise<void>;
+  patchSignals(
+    signals: Record<string, unknown>,
+    options?: { onlyIfMissing?: boolean },
+  ): void;
 
   /**
-   * Update DOM elements
+   * Update DOM elements via patching
    *
    * @param html - HTML content (must include element with id for targeting)
-   * @param options - Optional mode and selector
+   * @param options - Optional patch mode, selector, and view transition
    *
    * @example
    * ```ts
-   * // Replace element with matching id (default: morph)
+   * // Outer patch element with matching id (default)
    * await stream.patchElements('<div id="content">New content</div>');
    *
    * // Append to a container
@@ -58,19 +72,56 @@ export interface SSEStream {
    * });
    * ```
    */
-  patchElements(html: string, options?: { mode?: PatchMode; selector?: string }): Promise<void>;
+  patchElements(
+    html: string,
+    options?: {
+      mode?: PatchMode;
+      selector?: string;
+      useViewTransition?: boolean;
+    },
+  ): void;
 
   /**
-   * Execute JavaScript on the client
+   * Redirect the client to a new URL
    *
-   * @param script - JavaScript code to execute
+   * Uses patchElements internally to inject a script that navigates the client.
+   *
+   * @param url - The URL to redirect to
    *
    * @example
    * ```ts
-   * await stream.executeScript('console.log("Hello from server")');
+   * await stream.redirect('/dash/posts');
    * ```
    */
-  executeScript(script: string): Promise<void>;
+  redirect(url: string): void;
+
+  /**
+   * Remove elements matching a CSS selector
+   *
+   * @param selector - CSS selector for elements to remove
+   *
+   * @example
+   * ```ts
+   * await stream.remove('#placeholder');
+   * ```
+   */
+  remove(selector: string): void;
+}
+
+/**
+ * Format a single SSE event string
+ *
+ * @param eventType - The Datastar event type (e.g. "datastar-patch-elements")
+ * @param dataLines - Array of "key value" data lines
+ * @returns Formatted SSE event string
+ */
+function formatEvent(eventType: string, dataLines: readonly string[]): string {
+  let event = `event: ${eventType}\n`;
+  for (const line of dataLines) {
+    event += `data: ${line}\n`;
+  }
+  event += "\n";
+  return event;
 }
 
 /**
@@ -78,13 +129,13 @@ export interface SSEStream {
  *
  * @param c - Hono context
  * @param handler - Async function that writes to the SSE stream
+ * @param options - Optional response options (e.g. headers for cookie forwarding)
  * @returns Response with SSE content-type
  *
  * @example
  * ```ts
  * app.post("/api/upload", (c) => {
  *   return sse(c, async (stream) => {
- *     // Process upload...
  *     await stream.patchSignals({ uploading: false });
  *     await stream.patchElements('<div id="new-item">...</div>', {
  *       mode: 'append',
@@ -92,55 +143,92 @@ export interface SSEStream {
  *     });
  *   });
  * });
+ *
+ * // With cookie forwarding (for auth)
+ * app.post("/signin", (c) => {
+ *   return sse(c, async (stream) => {
+ *     await stream.redirect('/dash');
+ *   }, { headers: { 'Set-Cookie': cookieValue } });
+ * });
  * ```
  */
-export function sse(c: Context, handler: (stream: SSEStream) => Promise<void>): Response {
+export function sse(
+  c: Context,
+  handler: (stream: SSEStream) => Promise<void>,
+  options?: { headers?: Record<string, string> },
+): Response {
   const encoder = new TextEncoder();
 
-  const stream = new ReadableStream({
+  const body = new ReadableStream({
     async start(controller) {
-      const write = (data: string) => {
-        controller.enqueue(encoder.encode(data));
-      };
-
-      const sseStream: SSEStream = {
-        async patchSignals(signals) {
-          write(`event: datastar-patch-signals\n`);
-          write(`data: signals ${JSON.stringify(signals)}\n\n`);
+      const stream: SSEStream = {
+        patchSignals(signals, opts) {
+          const dataLines: string[] = [`signals ${JSON.stringify(signals)}`];
+          if (opts?.onlyIfMissing) {
+            dataLines.push("onlyIfMissing true");
+          }
+          controller.enqueue(
+            encoder.encode(formatEvent("datastar-patch-signals", dataLines)),
+          );
         },
 
-        async patchElements(html, options = {}) {
-          write(`event: datastar-patch-elements\n`);
-          if (options.mode) {
-            write(`data: mode ${options.mode}\n`);
+        patchElements(html, opts) {
+          const dataLines: string[] = [];
+          // Each line of HTML gets its own "elements <line>" data line
+          for (const line of html.split("\n")) {
+            dataLines.push(`elements ${line}`);
           }
-          if (options.selector) {
-            write(`data: selector ${options.selector}\n`);
+          if (opts?.mode) {
+            dataLines.push(`mode ${opts.mode}`);
           }
-          // Escape newlines in HTML for SSE format
-          const escapedHtml = html.replace(/\n/g, "\ndata: ");
-          write(`data: elements ${escapedHtml}\n\n`);
+          if (opts?.selector) {
+            dataLines.push(`selector ${opts.selector}`);
+          }
+          if (opts?.useViewTransition) {
+            dataLines.push("useViewTransition true");
+          }
+          controller.enqueue(
+            encoder.encode(formatEvent("datastar-patch-elements", dataLines)),
+          );
+        },
+
+        redirect(url) {
+          const escapedUrl = url.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+          const script = `<script data-effect="el.remove()">window.location.href='${escapedUrl}'</script>`;
+          const dataLines: string[] = [
+            `elements ${script}`,
+            "mode append",
+            "selector body",
+          ];
+          controller.enqueue(
+            encoder.encode(formatEvent("datastar-patch-elements", dataLines)),
+          );
         },
 
-        async executeScript(script) {
-          write(`event: datastar-execute-script\n`);
-          write(`data: script ${script}\n\n`);
+        remove(selector) {
+          controller.enqueue(
+            encoder.encode(
+              formatEvent("datastar-patch-elements", [
+                "elements ",
+                `mode remove`,
+                `selector ${selector}`,
+              ]),
+            ),
+          );
         },
       };
 
-      try {
-        await handler(sseStream);
-      } finally {
-        controller.close();
-      }
+      await handler(stream);
+      controller.close();
     },
   });
 
-  return new Response(stream, {
-    headers: {
-      "Content-Type": "text/event-stream",
-      "Cache-Control": "no-cache",
-      Connection: "keep-alive",
-    },
-  });
+  const headers: Record<string, string> = {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+    ...options?.headers,
+  };
+
+  return new Response(body, { headers });
 }

package/src/middleware/auth.ts

@@ -21,7 +21,9 @@ export function requireAuth(redirectTo = "/signin"): MiddlewareHandler<Env> {
     }
 
     try {
-      const session = await c.var.auth.api.getSession({ headers: c.req.raw.headers });
+      const session = await c.var.auth.api.getSession({
+        headers: c.req.raw.headers,
+      });
 
       if (!session?.user) {
         return c.redirect(redirectTo);
@@ -45,7 +47,9 @@ export function requireAuthApi(): MiddlewareHandler<Env> {
     }
 
     try {
-      const session = await c.var.auth.api.getSession({ headers: c.req.raw.headers });
+      const session = await c.var.auth.api.getSession({
+        headers: c.req.raw.headers,
+      });
 
       if (!session?.user) {
         return c.json({ error: "Unauthorized" }, 401);

package/src/routes/api/posts.ts

@@ -32,8 +32,9 @@ postsApiRoutes.get("/", async (c) => {
       ...p,
       sqid: sqid.encode(p.id),
     })),
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Array length check guarantees element exists
-    nextCursor: posts.length === limit ? sqid.encode(posts[posts.length - 1]!.id) : null,
+
+    nextCursor:
+      posts.length === limit ? sqid.encode(posts[posts.length - 1]!.id) : null,
   });
 });
 
@@ -55,7 +56,10 @@ postsApiRoutes.post("/", requireAuthApi(), async (c) => {
   // Validate request body
   const parseResult = CreatePostSchema.safeParse(rawBody);
   if (!parseResult.success) {
-    return c.json({ error: "Validation failed", details: parseResult.error.flatten() }, 400);
+    return c.json(
+      { error: "Validation failed", details: parseResult.error.flatten() },
+      400,
+    );
   }
 
   const body = parseResult.data;
@@ -68,7 +72,9 @@ postsApiRoutes.post("/", requireAuthApi(), async (c) => {
     sourceUrl: body.sourceUrl || undefined,
     sourceName: body.sourceName,
     path: body.path || undefined,
-    replyToId: body.replyToId ? (sqid.decode(body.replyToId) ?? undefined) : undefined,
+    replyToId: body.replyToId
+      ? (sqid.decode(body.replyToId) ?? undefined)
+      : undefined,
     publishedAt: body.publishedAt,
   });
 
@@ -85,7 +91,10 @@ postsApiRoutes.put("/:id", requireAuthApi(), async (c) => {
   // Validate request body
   const parseResult = UpdatePostSchema.safeParse(rawBody);
   if (!parseResult.success) {
-    return c.json({ error: "Validation failed", details: parseResult.error.flatten() }, 400);
+    return c.json(
+      { error: "Validation failed", details: parseResult.error.flatten() },
+      400,
+    );
   }
 
   const body = parseResult.data;

package/src/routes/api/upload.ts

@@ -33,7 +33,7 @@ function renderMediaCard(
     size: number;
   },
   r2PublicUrl?: string,
-  imageTransformUrl?: string
+  imageTransformUrl?: string,
 ): string {
   const fullUrl = getMediaUrl(media.id, media.r2Key, r2PublicUrl);
   const thumbnailUrl = getImageUrl(fullUrl, imageTransformUrl, {
@@ -79,7 +79,9 @@ function renderMediaCard(
         href="/dash/media/${media.id}"
         class="block aspect-square bg-muted rounded-lg overflow-hidden border hover:border-primary"
       >
-        <div class="w-full h-full flex items-center justify-center text-muted-foreground">
+        <div
+          class="w-full h-full flex items-center justify-center text-muted-foreground"
+        >
           <span class="text-xs">${media.mimeType}</span>
         </div>
       </a>
@@ -104,7 +106,9 @@ function formatSize(bytes: number): string {
 /**
  * Check if request wants SSE response (from Datastar)
  */
-function wantsSSE(c: { req: { header: (name: string) => string | undefined } }): boolean {
+function wantsSSE(c: {
+  req: { header: (name: string) => string | undefined };
+}): boolean {
   const accept = c.req.header("accept") || "";
   return accept.includes("text/event-stream");
 }
@@ -114,7 +118,9 @@ uploadApiRoutes.post("/", async (c) => {
   if (!c.env.R2) {
     if (wantsSSE(c)) {
       return sse(c, async (stream) => {
-        await stream.patchSignals({ _uploadError: "R2 storage not configured" });
+        await stream.patchSignals({
+          _uploadError: "R2 storage not configured",
+        });
       });
     }
     return c.json({ error: "R2 storage not configured" }, 500);
@@ -133,7 +139,13 @@ uploadApiRoutes.post("/", async (c) => {
   }
 
   // Validate file type
-  const allowedTypes = ["image/jpeg", "image/png", "image/gif", "image/webp", "image/svg+xml"];
+  const allowedTypes = [
+    "image/jpeg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+    "image/svg+xml",
+  ];
   if (!allowedTypes.includes(file.type)) {
     if (wantsSSE(c)) {
       return sse(c, async (stream) => {
@@ -148,7 +160,9 @@ uploadApiRoutes.post("/", async (c) => {
   if (file.size > maxSize) {
     if (wantsSSE(c)) {
       return sse(c, async (stream) => {
-        await stream.patchSignals({ _uploadError: "File too large (max 10MB)" });
+        await stream.patchSignals({
+          _uploadError: "File too large (max 10MB)",
+        });
       });
     }
     return c.json({ error: "File too large (max 10MB)" }, 400);
@@ -180,7 +194,11 @@ uploadApiRoutes.post("/", async (c) => {
 
     // SSE response for Datastar
     if (wantsSSE(c)) {
-      const cardHtml = renderMediaCard(media, c.env.R2_PUBLIC_URL, c.env.IMAGE_TRANSFORM_URL);
+      const cardHtml = renderMediaCard(
+        media,
+        c.env.R2_PUBLIC_URL,
+        c.env.IMAGE_TRANSFORM_URL,
+      );
 
       return sse(c, async (stream) => {
         // Replace placeholder with real media card