@mauroandre/velojs 0.0.18 → 0.0.19

package/README.md

@@ -501,6 +501,136 @@ export const action_login = async ({ body }: { body: LoginBody }) => {
 
 **Error handling**: Actions do NOT throw on server errors. They resolve with `{ error: "message" }`. Always check `result.error` explicitly.
 
+### Shared actions in Layouts
+
+Actions are tied to the module where they're declared — the route is always `/_action/{moduleId}/{actionName}`. Declare an action in a Layout and import it from any child module to share it across multiple pages.
+
+```typescript
+// app/admin/Layout.tsx — action declared once in the layout
+import type { ActionArgs } from "@mauroandre/velojs";
+
+export const action_logout = async ({ c }: ActionArgs) => {
+    const { deleteCookie } = await import("@mauroandre/velojs/cookie");
+    deleteCookie(c!, "session");
+    return { ok: true };
+};
+
+export const Component = ({ children }) => (/* layout with children */);
+```
+
+```typescript
+// app/admin/Dashboard.tsx — imports and uses the action from Layout
+import { action_logout } from "./Layout.js";
+
+export const Component = () => (
+    <button onClick={async () => {
+        await action_logout({});
+        window.location.href = "/login";
+    }}>Logout</button>
+);
+```
+
+The client-side transform rewrites the import to fetch `/_action/admin/Layout/logout`, so the action always points to the correct URL regardless of where it's imported. Middlewares on the Layout apply automatically.
+
+---
+
+## Event Streams
+
+Push real-time updates from server to client via Server-Sent Events (SSE). Useful for live progress, notifications, metrics, log streaming, AI tokens, and any server → client push scenario.
+
+### `stream_*` convention
+
+Declare a stream alongside `loader` / `action_*` in any page or layout module. The framework registers an SSE route at `/_event/{moduleId}/{name}` automatically:
+
+```typescript
+// app/admin/Deploy.tsx
+import { createEventStream } from "@mauroandre/velojs";
+import { useEventStream, useParams } from "@mauroandre/velojs/hooks";
+
+type DeployState = { step: string; status: "running" | "success" | "error" };
+
+const activeDeploys = new Map<string, DeployState>();
+
+export const stream_progress = createEventStream<DeployState>({
+    channel: (c) => c.req.query("channel") ?? "",
+    snapshot: (channel) => activeDeploys.get(channel ?? ""),
+    closeOn: (s) => s.status === "success" || s.status === "error",
+});
+
+export const Component = () => {
+    const params = useParams<{ id: string }>();
+    const { data, snapshot, closed } = useEventStream(stream_progress, {
+        channel: params.id,
+    });
+
+    const state = data.value ?? snapshot.value;
+    return <div>{state?.step ?? "waiting..."}</div>;
+};
+```
+
+Emit from any service that imports the stream:
+
+```typescript
+import { stream_progress } from "./Deploy.js";
+
+stream_progress.emit("app-123", { step: "building", status: "running" });
+```
+
+### Standalone streams
+
+For cross-cutting streams (global metrics, notifications) consumed by many pages, use an explicit `path`:
+
+```typescript
+// app/streams/metrics.ts
+export const metricsStream = createEventStream<Metric[]>({
+    path: "/api/metrics/containers",
+});
+
+setInterval(() => metricsStream.emit(collectMetrics()), 2000);
+```
+
+### Configuration
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `path` | `string` | (Standalone) Explicit URL path |
+| `channel` | `(c: Context) => string` | Extract channel ID from request — subscribers only get matching events |
+| `snapshot` | `(channel) => TSnapshot \| undefined` | Returns current state on connect (and reconnect) |
+| `closeOn` | `(event: TEvent) => boolean` | Closes the SSE connection when matching event is sent |
+| `heartbeatMs` | `number \| false` | Keep-alive heartbeat interval, default `20000` (20s). `false` to disable |
+| `middlewares` | `MiddlewareHandler[]` | (Standalone) Hono middlewares applied to the SSE route |
+
+### Middleware inheritance
+
+Streams declared with `stream_*` automatically inherit middlewares from parent route nodes — same as pages and actions. A stream under an `AdminLayout` with `authMiddleware` is protected without extra wiring.
+
+For standalone streams, pass middlewares explicitly:
+
+```typescript
+export const metricsStream = createEventStream<Metric[]>({
+    path: "/api/metrics",
+    middlewares: [authMiddleware],
+});
+```
+
+### `useEventStream` hook
+
+```typescript
+const { data, snapshot, closed, error } = useEventStream(stream, {
+    channel: "deploy-123",  // optional
+    enabled: true,          // optional
+});
+```
+
+| Signal | Description |
+|--------|-------------|
+| `data` | Latest event received from the server |
+| `snapshot` | Initial state on connect (if `snapshot` is configured) |
+| `closed` | `true` when server closed the stream (`closeOn` matched) |
+| `error` | Parse or connection error, if any |
+
+The hook handles `EventSource` lifecycle automatically: opens on mount, closes on unmount, re-opens when `channel` changes.
+
 ---
 
 ## Hooks
@@ -511,6 +641,7 @@ All hooks work in both SSR and client (via AsyncLocalStorage on server, wouter/D
 |------|-------------|
 | `useLoader<T>(deps?)` | Loader data with SSR + SPA support. Returns `{ data, loading, refetch }` |
 | `Loader<T>()` | Module-level SSR-only loader. Returns `{ data, loading }` |
+| `useEventStream<T, S>(stream, opts?)` | Subscribe to a server-sent event stream. Returns `{ data, snapshot, closed, error }` |
 | `useParams<T>()` | Route parameters (e.g., `:id`) |
 | `useQuery<T>()` | Query string parameters |
 | `useNavigate()` | Programmatic navigation. Returns `navigate(path)` function |
@@ -701,7 +832,25 @@ export default [
 
 ### Inheritance
 
-Middlewares accumulate from parent to child. In the example above, `/master/workers` runs `authMiddleware` first, then `masterMiddleware`. This applies to both page loads (loaders) and action calls.
+Middlewares accumulate from parent to child and apply to **every nested route**, including:
+
+- **Page routes** (GET) — when loading a page
+- **Action routes** (POST `/_action/...`) — when calling a server action
+- **Data fetches** (GET with `?_data=1`) — during SPA navigation
+
+In the example above, `/master/workers` runs `authMiddleware` first, then `masterMiddleware`. The same applies when calling `action_*` functions from any page under `MasterLayout` — both middlewares run before the action executes.
+
+```typescript
+// This action, defined in app/master/Workers.tsx, is registered as
+// POST /_action/master/Workers/delete
+// with authMiddleware + masterMiddleware applied.
+export const action_delete = async ({ body, c }: ActionArgs<{ id: string }>) => {
+    const user = c!.get("user"); // set by authMiddleware
+    // ...
+};
+```
+
+A middleware on a Layout guards everything underneath it — pages, loaders, and actions — with no extra wiring.
 
 ### Accessing middleware data in loaders and actions
 
@@ -927,10 +1076,11 @@ Hooks (`useParams`, `useQuery`, `usePathname`, `Loader`, `useLoader`) access thi
 
 | Import | Contents |
 |--------|----------|
-| `@mauroandre/velojs` | Types (`AppRoutes`, `ActionArgs`, `LoaderArgs`, `Metadata`), `Scripts`, `Link`, `defineConfig` |
+| `@mauroandre/velojs` | Types (`AppRoutes`, `ActionArgs`, `LoaderArgs`, `Metadata`, `EventStream`, `EventStreamConfig`), `Scripts`, `Link`, `createEventStream`, `defineConfig` |
 | `@mauroandre/velojs/server` | `startServer`, `createApp`, `addRoutes`, `onServer`, `serverDataStorage` |
 | `@mauroandre/velojs/client` | `startClient` |
-| `@mauroandre/velojs/hooks` | `Loader`, `useLoader`, `useParams`, `useQuery`, `useNavigate`, `usePathname`, `touch` |
+| `@mauroandre/velojs/hooks` | `Loader`, `useLoader`, `useEventStream`, `useParams`, `useQuery`, `useNavigate`, `usePathname`, `touch` |
+| `@mauroandre/velojs/events` | `createEventStream`, `EventStream`, `EventStreamConfig` (also re-exported from root) |
 | `@mauroandre/velojs/cookie` | `getCookie`, `setCookie`, `deleteCookie`, `getSignedCookie`, `setSignedCookie` |
 | `@mauroandre/velojs/factory` | `createMiddleware`, `createFactory` |
 | `@mauroandre/velojs/vite` | `veloPlugin` |

package/dist/events.d.ts

@@ -0,0 +1,91 @@
+/**
+ * VeloJS Event Streams
+ * Server-Sent Events (SSE) with snapshot, channels, and auto-close.
+ *
+ * Two ways to use:
+ *
+ * 1. Standalone (cross-cutting streams like global metrics):
+ * ```typescript
+ * export const metricsStream = createEventStream<Metric[]>({
+ *     path: "/api/metrics",
+ * });
+ * metricsStream.emit(currentMetrics);
+ * ```
+ *
+ * 2. Convention `stream_*` (per-page streams, route registered automatically):
+ * ```typescript
+ * // app/admin/Deploy.tsx
+ * export const stream_progress = createEventStream<DeployState>({
+ *     channel: (c) => c.req.param("id"),
+ *     snapshot: (id) => activeDeploys.get(id),
+ *     closeOn: (s) => s.status === "success" || s.status === "error",
+ * });
+ * ```
+ */
+import type { Context, Hono, MiddlewareHandler } from "hono";
+export interface EventStreamConfig<TEvent, TSnapshot = TEvent> {
+    /**
+     * Explicit URL path for the SSE endpoint (standalone usage).
+     * When omitted, the path is derived from the module ID at build time
+     * (convention `stream_*`).
+     */
+    path?: string;
+    /**
+     * Channel selector — extracts a channel ID from the request.
+     * Subscribers only receive events emitted to their channel.
+     * When omitted, the stream is a broadcast (all subscribers receive all events).
+     */
+    channel?: (c: Context) => string;
+    /**
+     * Returns the current state of a channel for snapshot-on-connect.
+     * Sent before any new events to bring the client up to date.
+     * Must remain available even after the stream "closes" — clients reconnecting
+     * after a terminal event still need to see the final state.
+     */
+    snapshot?: (channel: string | undefined) => TSnapshot | undefined | Promise<TSnapshot | undefined>;
+    /**
+     * Returns true when an event marks the end of the stream for that channel.
+     * The server closes the SSE connection after sending such an event.
+     */
+    closeOn?: (event: TEvent) => boolean;
+    /**
+     * Heartbeat interval in milliseconds. Sends `:heartbeat\n\n` to keep
+     * proxies (Cloudflare, Nginx, ALB) from closing idle connections.
+     * Default: 20000 (20s). Set to `false` to disable.
+     */
+    heartbeatMs?: number | false;
+    /**
+     * Middlewares to apply to the SSE route (standalone streams only).
+     * For `stream_*` convention streams, middlewares are inherited from
+     * parent route nodes automatically.
+     */
+    middlewares?: MiddlewareHandler[];
+}
+export interface EventStream<TEvent, TSnapshot = TEvent> {
+    /** Broadcast emit (no channel) */
+    emit(event: TEvent): void;
+    /** Channel-targeted emit */
+    emit(channel: string, event: TEvent): void;
+    /** Internal: marker for runtime detection */
+    readonly __isVeloEventStream: true;
+    /** Internal: configuration */
+    readonly __config: EventStreamConfig<TEvent, TSnapshot>;
+    /** Internal: registered listeners by channel ("" for broadcast) */
+    readonly __listeners: Map<string, Set<(event: TEvent) => void>>;
+    /** Internal: assigned URL path (set by standalone or by stream_* discovery) */
+    __path: string | undefined;
+}
+/**
+ * Returns and clears the queue of pending standalone streams.
+ * Called by createApp to register their routes.
+ */
+export declare function flushPendingStreamRoutes(app: Hono): void;
+/**
+ * Creates a typed event stream with optional channel, snapshot, and close-on-event.
+ */
+export declare function createEventStream<TEvent, TSnapshot = TEvent>(config?: EventStreamConfig<TEvent, TSnapshot>): EventStream<TEvent, TSnapshot>;
+/**
+ * Registers a GET SSE route for the given stream at the given path.
+ * Used both by standalone streams and by stream_* discovery.
+ */
+export declare function registerStreamHandler<TEvent, TSnapshot>(app: Hono, path: string, stream: EventStream<TEvent, TSnapshot>, middlewares?: Array<(c: Context, next: () => Promise<void>) => any>): void;

package/dist/events.js

@@ -0,0 +1,62 @@
+const A = [];
+function w(t) {
+  for (const s of A) s(t);
+  A.length = 0;
+}
+function N(t = {}) {
+  const s = /* @__PURE__ */ new Map();
+  function e(a, f) {
+    let l, n;
+    arguments.length === 1 ? (l = "", n = a) : (l = a, n = f);
+    const c = s.get(l);
+    if (c)
+      for (const h of c) h(n);
+  }
+  const r = {
+    emit: e,
+    __isVeloEventStream: !0,
+    __config: t,
+    __listeners: s,
+    __path: t.path
+  };
+  return t.path && A.push((a) => {
+    p(a, t.path, r, t.middlewares ?? []);
+  }), r;
+}
+function p(t, s, e, r = []) {
+  const a = async (f) => {
+    const { streamSSE: l } = await import("hono/streaming"), n = e.__config.channel ? e.__config.channel(f) : "", c = e.__config.heartbeatMs, h = c === !1 ? 0 : c ?? 2e4;
+    return l(f, async (_) => {
+      if (e.__config.snapshot) {
+        const o = await e.__config.snapshot(
+          n === "" ? void 0 : n
+        );
+        o !== void 0 && await _.writeSSE({
+          event: "snapshot",
+          data: JSON.stringify(o)
+        });
+      }
+      let E;
+      const T = new Promise((o) => {
+        E = o;
+      });
+      let S = !1, u = null, i;
+      const d = () => {
+        S || (S = !0, u && clearInterval(u), i?.delete(g), i?.size === 0 && e.__listeners.delete(n), E());
+      }, g = (o) => {
+        S || (_.writeSSE({ data: JSON.stringify(o) }).catch(() => {
+        }), e.__config.closeOn?.(o) && (_.close(), d()));
+      };
+      i = e.__listeners.get(n), i || (i = /* @__PURE__ */ new Set(), e.__listeners.set(n, i)), i.add(g), u = h > 0 ? setInterval(() => {
+        S || _.writeSSE({ event: "heartbeat", data: "" }).catch(() => {
+        });
+      }, h) : null, _.onAbort(d), await T;
+    });
+  };
+  r.length > 0 ? t.on(["GET"], [s], ...r, a) : t.on(["GET"], [s], a);
+}
+export {
+  N as createEventStream,
+  w as flushPendingStreamRoutes,
+  p as registerStreamHandler
+};

package/dist/hooks.d.ts

@@ -1,4 +1,5 @@
 import { type Signal } from "@preact/signals";
+import type { EventStream } from "./events.js";
 export declare const __veloUpdatePending: Signal<boolean>;
 /**
  * Força o signal a notificar mudanças após mutação de propriedades aninhadas
@@ -118,3 +119,33 @@ export declare function useQuery<T extends Record<string, string> = Record<strin
  * ```
  */
 export declare function usePathname(): string;
+/**
+ * Subscribes to a server event stream (SSE) created with createEventStream.
+ *
+ * Returns:
+ * - `data`: Signal with the latest event received (null until first event)
+ * - `snapshot`: Signal with the initial snapshot if the server provided one
+ * - `closed`: Signal that becomes true when the stream is closed by the server
+ * - `error`: Signal with the connection error, if any
+ *
+ * Usage:
+ * ```tsx
+ * // Per-page stream (stream_* convention)
+ * const { data, snapshot } = useEventStream(stream_progress, { channel: deployId });
+ *
+ * // Standalone stream (no channel)
+ * const { data } = useEventStream(metricsStream);
+ * ```
+ *
+ * The connection closes automatically when the component unmounts or when
+ * the channel changes (re-opens with new channel).
+ */
+export declare function useEventStream<TEvent, TSnapshot = TEvent>(stream: EventStream<TEvent, TSnapshot>, options?: {
+    channel?: string;
+    enabled?: boolean;
+}): {
+    data: Signal<TEvent | null>;
+    snapshot: Signal<TSnapshot | null>;
+    closed: Signal<boolean>;
+    error: Signal<Error | null>;
+};

package/dist/hooks.js

@@ -1,61 +1,61 @@
-import { signal as _, useSignal as d } from "@preact/signals";
-import { useRef as g, useEffect as h } from "preact/hooks";
-import { useLocation as v, useParams as D } from "wouter-preact";
-const p = _(!1);
-function m(e) {
+import { signal as v, useSignal as c } from "@preact/signals";
+import { useEffect as h, useRef as p } from "preact/hooks";
+import { useLocation as w, useParams as g } from "wouter-preact";
+const S = v(!1);
+function L(e) {
   e.value !== null && typeof e.value == "object" && (e.value = { ...e.value });
 }
-function P(e) {
-  const a = _(!1);
+function m(e) {
+  const o = v(!1);
   if (typeof window > "u")
     return { data: {
       get value() {
         return e ? globalThis.__veloServerData?.getStore?.()?.[e] ?? null : null;
       }
-    }, loading: a };
+    }, loading: o };
   const t = window.__PAGE_DATA__, n = e && t?.[e] ? t[e] : null;
-  return { data: _(n), loading: a };
+  return { data: v(n), loading: o };
 }
-function T(e, a) {
+function A(e, o) {
   let t, n;
-  Array.isArray(e) ? n = e : (t = e, n = a);
+  Array.isArray(e) ? n = e : (t = e, n = o);
   let r = null;
   if (typeof window > "u" && t) {
-    const c = globalThis.__veloServerData?.getStore?.();
-    c?.[t] && (r = c[t]);
+    const l = globalThis.__veloServerData?.getStore?.();
+    l?.[t] && (r = l[t]);
   }
   if (typeof window < "u" && t) {
-    const o = window.__PAGE_DATA__;
-    o?.[t] && (r = o[t], delete o[t]);
+    const a = window.__PAGE_DATA__;
+    a?.[t] && (r = a[t], delete a[t]);
   }
-  const u = d(r), i = d(!1), l = () => {
+  const u = c(r), s = c(!1), _ = () => {
     if (typeof window > "u" || !t) return;
-    const o = window.location.pathname;
-    i.value = !0;
-    const w = typeof __VELO_STATIC__ < "u" && __VELO_STATIC__ ? `${o === "/" ? "" : o}/index.json` : (() => {
-      const s = new URLSearchParams(window.location.search);
-      return s.set("_data", "1"), `${o}?${s.toString()}`;
+    const a = window.location.pathname;
+    s.value = !0;
+    const f = typeof __VELO_STATIC__ < "u" && __VELO_STATIC__ ? `${a === "/" ? "" : a}/index.json` : (() => {
+      const i = new URLSearchParams(window.location.search);
+      return i.set("_data", "1"), `${a}?${i.toString()}`;
     })();
-    fetch(w, { cache: "no-cache" }).then((s) => s.json()).then((s) => {
-      typeof __VELO_BUILD_HASH__ < "u" && s.__buildHash && s.__buildHash !== __VELO_BUILD_HASH__ && (p.value = !0), u.value = s[t], i.value = !1;
+    fetch(f, { cache: "no-cache" }).then((i) => i.json()).then((i) => {
+      typeof __VELO_BUILD_HASH__ < "u" && i.__buildHash && i.__buildHash !== __VELO_BUILD_HASH__ && (S.value = !0), u.value = i[t], s.value = !1;
     }).catch(() => {
-      i.value = !1;
+      s.value = !1;
     });
-  }, f = g(r !== null);
+  }, d = p(r !== null);
   return h(() => {
-    if (f.current) {
-      f.current = !1;
+    if (d.current) {
+      d.current = !1;
       return;
     }
-    l();
-  }, n ?? []), { data: u, loading: i, refetch: l };
+    _();
+  }, n ?? []), { data: u, loading: s, refetch: _ };
 }
-function L() {
-  const [, e] = v();
+function P() {
+  const [, e] = w();
   return e;
 }
-function E() {
-  return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__params ?? {} : D();
+function T() {
+  return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__params ?? {} : g();
 }
 function b() {
   if (typeof window > "u")
@@ -63,21 +63,52 @@ function b() {
   const e = window.__PAGE_DATA__;
   if (e?.__query)
     return e.__query;
-  const a = new URLSearchParams(window.location.search), t = {};
-  return a.forEach((n, r) => {
+  const o = new URLSearchParams(window.location.search), t = {};
+  return o.forEach((n, r) => {
     t[r] = n;
   }), t;
 }
 function H() {
-  return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__pathname ?? "/" : (v(), window.location.pathname);
+  return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__pathname ?? "/" : (w(), window.location.pathname);
+}
+function U(e, o = {}) {
+  const t = c(null), n = c(null), r = c(!1), u = c(null), { channel: s, enabled: _ = !0 } = o;
+  return h(() => {
+    if (typeof window > "u" || !_) return;
+    if (!e.__path) {
+      console.warn("[velojs] useEventStream: stream has no __path");
+      return;
+    }
+    t.value = null, n.value = null, r.value = !1, u.value = null;
+    const d = s ? `${e.__path}?channel=${encodeURIComponent(s)}` : e.__path, a = new EventSource(d);
+    return a.addEventListener("snapshot", (l) => {
+      try {
+        n.value = JSON.parse(l.data);
+      } catch (f) {
+        u.value = f;
+      }
+    }), a.addEventListener("message", (l) => {
+      try {
+        t.value = JSON.parse(l.data);
+      } catch (f) {
+        u.value = f;
+      }
+    }), a.addEventListener("heartbeat", () => {
+    }), a.addEventListener("error", () => {
+      a.readyState === EventSource.CLOSED && (r.value = !0);
+    }), () => {
+      a.close();
+    };
+  }, [e, s, _]), { data: t, snapshot: n, closed: r, error: u };
 }
 export {
-  P as Loader,
-  p as __veloUpdatePending,
-  m as touch,
-  T as useLoader,
-  L as useNavigate,
-  E as useParams,
+  m as Loader,
+  S as __veloUpdatePending,
+  L as touch,
+  U as useEventStream,
+  A as useLoader,
+  P as useNavigate,
+  T as useParams,
   H as usePathname,
   b as useQuery
 };

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export type { AppRoutes, RouteNode, RouteModule, LoaderArgs, ActionArgs, Metadat
 export type { VeloConfig } from "./config.js";
 export { defineConfig } from "./config.js";
 export { Scripts, Link } from "./components.js";
+export { createEventStream } from "./events.js";
+export type { EventStream, EventStreamConfig } from "./events.js";
 export type { Context, MiddlewareHandler, Next } from "hono";

package/dist/index.js

@@ -1,7 +1,9 @@
-import { defineConfig as e } from "./config.js";
-import { Link as i, Scripts as n } from "./components.js";
+import { defineConfig as o } from "./config.js";
+import { Link as f, Scripts as i } from "./components.js";
+import { createEventStream as n } from "./events.js";
 export {
-  i as Link,
-  n as Scripts,
-  e as defineConfig
+  f as Link,
+  i as Scripts,
+  n as createEventStream,
+  o as defineConfig
 };