@mauroandre/velojs 0.0.55 → 0.0.57

package/dist/hooks.js

@@ -1,125 +1,144 @@
-import { signal as w, useSignal as u } from "@preact/signals";
-import { useEffect as E, useRef as S } from "preact/hooks";
-import { useLocation as b, useParams as O, useSearch as $ } from "wouter-preact";
-import { refetchModule as D, loaderLoading as m, loaderEntry as N } from "./loader-store.js";
-import { __veloUpdatePending as z } from "./loader-store.js";
-function U() {
+import { signal as S, useSignal as s } from "@preact/signals";
+import { useEffect as m, useRef as E } from "preact/hooks";
+import { useLocation as b, useParams as $, useSearch as B } from "wouter-preact";
+import { refetchModule as C, loaderLoading as D, loaderEntry as N } from "./loader-store.js";
+import { __veloUpdatePending as X } from "./loader-store.js";
+import { loaderFreshness as w, moduleChannelFreshness as O } from "./live-loader.js";
+function j() {
   return typeof window > "u" ? {} : window.__VELO_BOOT__ ?? {};
 }
-function W(e) {
-  const n = e.value;
-  n === null || typeof n != "object" || (e.value = Array.isArray(n) ? [...n] : { ...n });
+function F(e) {
+  const t = e.value;
+  t === null || typeof t != "object" || (e.value = Array.isArray(t) ? [...t] : { ...t });
 }
-function j(e) {
+function J(e) {
   return typeof window > "u" ? {
     data: {
       get value() {
         return e ? globalThis.__veloServerData?.getStore?.()?.[e] ?? null : null;
       }
     },
-    loading: w(!1),
+    loading: S(!1),
     refetch: () => {
-    }
+    },
+    freshness: w(),
+    freshnessByChannel: S({})
   } : e ? {
     data: N(e),
-    loading: m(e),
-    refetch: () => D(e)
-  } : { data: w(null), loading: w(!1), refetch: () => {
-  } };
+    loading: D(e),
+    refetch: () => C(e),
+    freshness: w(),
+    freshnessByChannel: O(e)
+  } : {
+    data: S(null),
+    loading: S(!1),
+    refetch: () => {
+    },
+    freshness: w(),
+    freshnessByChannel: S({})
+  };
 }
-function B(e, n) {
-  let t, r;
-  if (Array.isArray(e) ? r = e : (t = e, r = n), typeof window > "u") {
-    let g = null;
-    if (t) {
-      const h = globalThis.__veloServerData?.getStore?.();
-      h?.[t] && (g = h[t]);
+function M(e, t) {
+  let n, r;
+  if (Array.isArray(e) ? r = e : (n = e, r = t), typeof window > "u") {
+    let a = null;
+    if (n) {
+      const v = globalThis.__veloServerData?.getStore?.();
+      v?.[n] && (a = v[n]);
     }
     return {
-      data: u(g),
-      loading: u(!1),
+      data: s(a),
+      loading: s(!1),
       refetch: () => {
-      }
+      },
+      freshness: w(),
+      freshnessByChannel: s({})
     };
   }
-  if (!t)
-    return { data: u(null), loading: u(!1), refetch: () => {
-    } };
-  const o = N(t), a = m(t), l = () => D(t), d = S(!0);
-  return E(() => {
-    d.current && (d.current = !1, o.value !== null) || l();
-  }, r ?? []), { data: o, loading: a, refetch: l };
+  if (!n)
+    return {
+      data: s(null),
+      loading: s(!1),
+      refetch: () => {
+      },
+      freshness: w(),
+      freshnessByChannel: s({})
+    };
+  const l = N(n), o = D(n), u = () => C(n), h = w(), y = E(!0);
+  return m(() => {
+    y.current && (y.current = !1, l.value !== null) || u();
+  }, r ?? []), { data: l, loading: o, refetch: u, freshness: h, freshnessByChannel: O(n) };
 }
-function J() {
+function q() {
   const [, e] = b();
   return e;
 }
-function M() {
-  return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__params ?? {} : O();
+function x() {
+  return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__params ?? {} : $();
 }
-function q() {
+function G() {
   if (typeof window > "u")
     return globalThis.__veloServerData?.getStore?.()?.__query ?? {};
-  const e = $(), n = {};
-  return new URLSearchParams(e).forEach((t, r) => {
-    n[r] = t;
-  }), n;
+  const e = B(), t = {};
+  return new URLSearchParams(e).forEach((n, r) => {
+    t[r] = n;
+  }), t;
 }
-function x() {
+function Q() {
   return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__pathname ?? "/" : (b(), window.location.pathname);
 }
-function G(e, n = {}) {
-  const t = u(null), r = u(null), o = u(!1), a = u(null), { channel: l, enabled: d = !0 } = n;
-  return E(() => {
-    if (typeof window > "u" || !d) return;
+function V(e, t = {}) {
+  const n = s(null), r = s(null), l = s(!1), o = s(null), { channel: u, enabled: h = !0 } = t;
+  return m(() => {
+    if (typeof window > "u" || !h) return;
     if (!e.__path) {
       console.warn("[velojs] useEventStream: stream has no __path");
       return;
     }
-    o.value = !1, a.value = null;
-    const g = l ? `${e.__path}?channel=${encodeURIComponent(l)}` : e.__path, s = new EventSource(g);
-    return s.addEventListener("snapshot", (h) => {
+    l.value = !1, o.value = null;
+    const y = u ? `${e.__path}?channel=${encodeURIComponent(u)}` : e.__path, a = new EventSource(y);
+    return a.addEventListener("snapshot", (g) => {
       try {
-        r.value = JSON.parse(h.data);
-      } catch (y) {
-        a.value = y;
+        r.value = JSON.parse(g.data);
+      } catch (v) {
+        o.value = v;
       }
-    }), s.addEventListener("message", (h) => {
+    }), a.addEventListener("message", (g) => {
       try {
-        t.value = JSON.parse(h.data);
-      } catch (y) {
-        a.value = y;
+        n.value = JSON.parse(g.data);
+      } catch (v) {
+        o.value = v;
       }
-    }), s.addEventListener("heartbeat", () => {
-    }), s.addEventListener("close", () => {
-      o.value = !0, s.close();
-    }), s.addEventListener("error", () => {
-      s.readyState === EventSource.CLOSED && (o.value = !0);
+    }), a.addEventListener("heartbeat", () => {
+    }), a.addEventListener("close", () => {
+      l.value = !0, a.close();
+    }), a.addEventListener("error", () => {
+      a.readyState === EventSource.CLOSED && (l.value = !0);
     }), () => {
-      s.close();
+      a.close();
     };
-  }, [e, l, d]), { data: t, snapshot: r, closed: o, error: a };
+  }, [e, u, h]), { data: n, snapshot: r, closed: l, error: o };
 }
-function F(e, n = {}) {
-  const t = u("connecting"), r = u(null), o = u(null), a = S(null), l = S([]), { channel: d, onMessage: g, onOpen: s, onClose: h, onError: y, enabled: L = !0 } = n;
-  return E(() => {
+function z(e, t = {}) {
+  const n = s("connecting"), r = s(null), l = s(null), o = E(null), u = E([]), { channel: h, onMessage: y, onOpen: a, onClose: g, onError: v, enabled: L = !0 } = t;
+  return m(() => {
     if (typeof window > "u" || !L) return;
     if (!e.__path) {
       console.warn("[velojs] useSocket: stub has no __path");
       return;
     }
-    t.value = "connecting", o.value = null;
-    const v = `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.host}`, i = d ? `${v}${e.__path}?channel=${encodeURIComponent(d)}` : `${v}${e.__path}`, f = new WebSocket(i);
-    return f.binaryType = "arraybuffer", a.current = f, f.addEventListener("open", () => {
-      t.value = "open";
-      const c = l.current;
-      l.current = [];
+    n.value = "connecting", l.value = null;
+    const d = `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.host}`, i = h ? `${d}${e.__path}?channel=${encodeURIComponent(h)}` : `${d}${e.__path}`, f = new WebSocket(i);
+    return f.binaryType = "arraybuffer", o.current = f, f.addEventListener("open", () => {
+      n.value = "open";
+      const c = u.current;
+      u.current = [];
       for (const _ of c)
         try {
           f.send(_);
         } catch {
         }
-      s?.();
+      a?.();
     }), f.addEventListener("message", (c) => {
       let _;
       if (typeof c.data == "string")
@@ -128,47 +147,47 @@ function F(e, n = {}) {
         _ = new Uint8Array(c.data);
       else
         return;
-      r.value = _, g?.(_);
+      r.value = _, y?.(_);
     }), f.addEventListener("close", (c) => {
-      t.value = "closed", a.current = null, h?.(c);
+      n.value = "closed", o.current = null, g?.(c);
     }), f.addEventListener("error", (c) => {
-      o.value = c, y?.(c);
+      l.value = c, v?.(c);
     }), () => {
-      a.current = null;
+      o.current = null;
       try {
         (f.readyState === WebSocket.OPEN || f.readyState === WebSocket.CONNECTING) && f.close();
       } catch {
       }
     };
-  }, [e.__path, d, L]), { send: (p) => {
-    let v;
-    typeof p == "string" || p instanceof Uint8Array ? v = p : v = JSON.stringify(p);
-    const i = a.current;
+  }, [e.__path, h, L]), { send: (p) => {
+    let d;
+    typeof p == "string" || p instanceof Uint8Array ? d = p : d = JSON.stringify(p);
+    const i = o.current;
     if (i && i.readyState === WebSocket.OPEN)
       try {
-        i.send(v);
+        i.send(d);
       } catch {
       }
-    else i && i.readyState === WebSocket.CONNECTING && l.current.push(v);
-  }, close: (p, v) => {
-    const i = a.current;
+    else i && i.readyState === WebSocket.CONNECTING && u.current.push(d);
+  }, close: (p, d) => {
+    const i = o.current;
     if (i)
       try {
-        i.close(p, v);
+        i.close(p, d);
       } catch {
       }
-  }, status: t, lastMessage: r, error: o };
+  }, status: n, lastMessage: r, error: l };
 }
 export {
-  j as Loader,
-  z as __veloUpdatePending,
-  W as touch,
-  U as useBoot,
-  G as useEventStream,
-  B as useLoader,
-  J as useNavigate,
-  M as useParams,
-  x as usePathname,
-  q as useQuery,
-  F as useSocket
+  J as Loader,
+  X as __veloUpdatePending,
+  F as touch,
+  j as useBoot,
+  V as useEventStream,
+  M as useLoader,
+  q as useNavigate,
+  x as useParams,
+  Q as usePathname,
+  G as useQuery,
+  z as useSocket
 };

package/dist/live-loader.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Live loader — client runtime.
+ *
+ * After hydration, every rendered module that declares `channels` opens one SSE
+ * connection per (module, channel) at `/_channel/{moduleId}/{channel}`. The
+ * connection declares the route params the module's path declares, extracted
+ * from the current URL and serialized in `?_route=` — the client declares the
+ * address it is already seeing, the server validates it against the declared
+ * path and decides the partition. The snapshot the connection receives — the
+ * connect snapshot and each emit's — replaces the value of the module's entry
+ * in the loader store, so the page stays faithful to server state without a
+ * line of code from the developer: `useLoader()`/`Loader()` handles keep the
+ * same signal instance and the reading component re-renders on its own.
+ *
+ * The connection is keyed by those params, not by the pathname: navigating
+ * between children of the same params keeps the connection; a move to another
+ * resource closes it and opens a new one.
+ *
+ * A `slice` event is the other delivery mode: the producer already holds the
+ * value, so the payload carries only the changed keys. A slice is merged
+ * shallowly by key onto the module's current value — the key sent is replaced
+ * by the whole value sent, keys not sent stay intact, and an absent key never
+ * means "removed" (removal is re-sending the key with the new whole value).
+ * The merge happens on arrival, never at render: slices that land in the same
+ * frame are accumulated and applied together before the next render, so none is
+ * lost, and for the same key the last one in arrival order wins. A malformed
+ * payload keeps the previous value, exactly like a malformed snapshot.
+ *
+ * A channel declared by a layout AND by a page produces one connection per
+ * module (each feeding its own module's signal); a single `emit` by channel
+ * name reaches both, because the server groups connections by channel and
+ * partition, not by module.
+ *
+ * `freshness` is aggregated per page: every connection closed → `"stale"`; a
+ * failed loader re-execution → `"error"`; otherwise `"live"`. A page with no
+ * channels stays `"live"` for its whole life, and a static build never opens a
+ * connection at all, so its freshness is constant `"live"` too.
+ *
+ * The per-channel refinement: `freshnessByChannel` is a signal record keyed by
+ * the channel names the module declares, so a page with two channels — one
+ * fallen, one following — shows both states at once. The aggregate folds it by
+ * the same rule: a silenced or closed channel counts as not-open.
+ *
+ * The silence detector is the client half of the idle timeout: a connection
+ * open but without deliveries for `CHANNEL_SILENCE_MS` (60s — a constant, not
+ * a configuration) is marked `"stale"` even though `EventSource` still reads
+ * `OPEN` — the tab in the background, the sleeping notebook, the proxy that
+ * stopped flushing without closing. Any delivery (or a reconnect's snapshot)
+ * brings the channel back to `"live"`. The server's heartbeat comment never
+ * generates a client event, so it cannot mask the silence.
+ */
+import { type Signal } from "@preact/signals";
+import type { ComponentChildren } from "preact";
+/** Freshness of the page's live data, as data for CSS to react to. */
+export type Freshness = "live" | "stale" | "error";
+/**
+ * How long an open connection may stay without a delivery (snapshot or slice)
+ * before the client calls it stale — the detector of the connection that a
+ * proxy silenced without closing. A runtime constant, documented, not a
+ * configuration: a channel goes stale on the wire's silence, not on the
+ * heartbeat (a comment generates no client event).
+ */
+export declare const CHANNEL_SILENCE_MS = 60000;
+/**
+ * The per-channel freshness signal of one module — what
+ * `useLoader()`/`Loader()` return as `freshnessByChannel`. Created empty: the
+ * keys appear as the module's connections open, the values follow them.
+ */
+export declare function moduleChannelFreshness(moduleId: string): Signal<Record<string, Freshness>>;
+/** The page-level freshness signal shared by every loader handle. */
+export declare function loaderFreshness(): Signal<Freshness>;
+/**
+ * Opens the SSE connection of one (module, channel) pair and feeds the module's
+ * loader-store entry with every snapshot and slice it receives. Returns the
+ * closer — the channel lives exactly as long as the module that declares it is
+ * mounted.
+ *
+ * `routeParams` are the params the module's route declares, extracted from the
+ * current URL: the client **declares** the address it is already seeing (the
+ * same information `?_data=1` carries on every SPA navigation), serialized in
+ * the `?_route=` query param of the connection. It is not free input — the
+ * server validates the keys against the module's path and rejects what the path
+ * does not declare.
+ *
+ * Inert (no connection, no freshness change) in a static build: there is no
+ * server to speak SSE.
+ */
+export declare function connectChannel(moduleId: string, channel: string, routeParams?: Record<string, string> | undefined): () => void;
+/**
+ * The params the module's route declares, extracted from a pathname. The
+ * module's `fullPath` matches as a **prefix** of the pathname: a layout
+ * declared at `/projeto/:id` covers `/projeto/7/sala` and extracts `id=7` —
+ * the child's suffix takes no part in the extraction. A path with a catch-all
+ * (`/docs/*`) declares no `:` key and yields the empty object, so the channel
+ * travels by principal.
+ */
+export declare function channelRouteParams(fullPath: string | undefined, pathname: string): Record<string, string>;
+/**
+ * Mounts the live channels of one route module. It renders its children
+ * unchanged (no DOM node, so SSR output and hydration are untouched) and only
+ * exists to tie the connection lifecycle to the module's own mount/unmount —
+ * SPA navigation and page close close the connections.
+ *
+ * The connection is **keyed by the params the module's route declares**, not
+ * by the pathname: navigating between children of the same params
+ * (`/projeto/7` → `/projeto/7/sala`) does not reconnect (the child's suffix is
+ * not part of the connection's identity), while a move to another resource
+ * (`/projeto/7` → `/projeto/9`) closes the old connection and opens a new one —
+ * with a fresh snapshot on connect, mirroring the loader store, which refetches
+ * when its own route's params move.
+ */
+export declare function ChannelBoundary({ moduleId, channels, fullPath, children, }: {
+    moduleId?: string | undefined;
+    channels?: readonly string[] | undefined;
+    /** The module's declared route path (`metadata.fullPath`) — its `:params`. */
+    fullPath?: string | undefined;
+    children?: ComponentChildren;
+}): ComponentChildren;
+/** Test-only. Drops every connection and resets every freshness signal. */
+export declare function __resetLiveLoader(): void;

package/dist/live-loader.js

@@ -0,0 +1,141 @@
+import { signal as v } from "@preact/signals";
+import { useEffect as m } from "preact/hooks";
+import { useLocation as g } from "wouter-preact";
+import { extractParams as _, loaderEntry as S } from "./loader-store.js";
+const L = 6e4, C = "snapshot", w = "slice", f = /* @__PURE__ */ new Set(), p = v("live"), y = /* @__PURE__ */ new Map();
+function R(e) {
+  let n = y.get(e);
+  return n || (n = v({}), y.set(e, n)), n;
+}
+function V() {
+  return p;
+}
+const u = /* @__PURE__ */ new Map();
+let h = !1;
+function N(e, n) {
+  let o = u.get(e);
+  o || (o = [], u.set(e, o)), o.push(n), !h && (h = !0, queueMicrotask(E));
+}
+function E() {
+  if (h = !1, u.size === 0) return;
+  const e = [...u];
+  u.clear();
+  for (const [n, o] of e) {
+    const s = S(n);
+    let t = s.value;
+    for (const l of o)
+      t = { ...t !== null && typeof t == "object" && !Array.isArray(t) ? t : {}, ...l };
+    s.value = t;
+  }
+}
+function T(e) {
+  if (typeof e != "string" || e.length === 0) return null;
+  try {
+    const n = JSON.parse(e);
+    return n === null || typeof n != "object" || Array.isArray(n) ? null : n;
+  } catch {
+    return null;
+  }
+}
+function O(e) {
+  return e.some((n) => n.failed) ? "error" : e.some((n) => n.state === "open" && !n.silent) ? "live" : "stale";
+}
+function a() {
+  let e = !1, n = !1;
+  for (const o of f)
+    o.failed && (e = !0), o.state === "open" && !o.silent && (n = !0);
+  e ? p.value = "error" : f.size > 0 && !n ? p.value = "stale" : p.value = "live";
+  for (const [o, s] of y) {
+    const t = /* @__PURE__ */ new Map();
+    for (const i of f) {
+      if (i.moduleId !== o) continue;
+      const r = t.get(i.channel);
+      r ? r.push(i) : t.set(i.channel, [i]);
+    }
+    const l = {};
+    for (const [i, r] of t)
+      l[i] = O(r);
+    s.value = l;
+  }
+}
+function A(e, n, o) {
+  if (typeof __VELO_STATIC__ < "u" && __VELO_STATIC__) return () => {
+  };
+  if (typeof window > "u" || typeof EventSource > "u")
+    return () => {
+    };
+  const s = {
+    state: "open",
+    failed: !1,
+    silent: !1,
+    moduleId: e,
+    channel: n
+  };
+  f.add(s), a();
+  let t = null;
+  const l = () => {
+    t !== null && clearTimeout(t), t = setTimeout(() => {
+      t = null, s.silent = !0, a();
+    }, L);
+  };
+  l();
+  const i = o && Object.keys(o).length > 0 ? `?_route=${encodeURIComponent(JSON.stringify(o))}` : "", r = new EventSource(
+    `/_channel/${encodeURI(e)}/${encodeURIComponent(n)}${i}`
+  );
+  return r.addEventListener(C, (c) => {
+    try {
+      E(), S(e).value = JSON.parse(c.data), s.state = "open", s.failed = !1, s.silent = !1, l(), a();
+    } catch {
+    }
+  }), r.addEventListener(w, (c) => {
+    const d = T(c.data);
+    d && (s.state = "open", s.failed = !1, s.silent = !1, l(), a(), N(e, d));
+  }), r.addEventListener("error", (c) => {
+    const d = c.data;
+    typeof d == "string" && d.length > 0 ? s.failed = !0 : s.state = r.readyState === EventSource.CLOSED ? "closed" : "reconnecting", a();
+  }), r.addEventListener("close", () => {
+    s.state = "closed", a();
+  }), () => {
+    f.delete(s), t !== null && clearTimeout(t);
+    try {
+      r.close();
+    } catch {
+    }
+    a();
+  };
+}
+function b(e, n) {
+  return e ? _(e, n) ?? {} : {};
+}
+function $({
+  moduleId: e,
+  channels: n,
+  fullPath: o,
+  children: s
+}) {
+  const t = n && n.length > 0 ? n.join(",") : "";
+  g();
+  const l = t === "" || typeof window > "u" ? "" : JSON.stringify(b(o, window.location.pathname));
+  return m(() => {
+    if (!e || t === "") return;
+    const i = l === "" ? void 0 : JSON.parse(l), r = t.split(",").map(
+      (c) => A(e, c, i)
+    );
+    return () => {
+      for (const c of r) c();
+    };
+  }, [e, t, l]), s;
+}
+function k() {
+  f.clear(), u.clear(), h = !1, p.value = "live";
+  for (const e of y.values()) e.value = {};
+}
+export {
+  L as CHANNEL_SILENCE_MS,
+  $ as ChannelBoundary,
+  k as __resetLiveLoader,
+  b as channelRouteParams,
+  A as connectChannel,
+  V as loaderFreshness,
+  R as moduleChannelFreshness
+};

package/dist/server.d.ts

@@ -1,6 +1,8 @@
 import { Hono } from "hono";
 import type { AppRoutes } from "./types.js";
 import { AsyncLocalStorage } from "node:async_hooks";
+export { emit, inspectChannels, registerChannels } from "./channels.js";
+export type { ChannelDefinition, ChannelMap, ChannelScopeContext, ChannelGroupOpenContext, ChannelGroupCloseContext, ChannelScopeResult, ChannelRegistryOptions, ChannelEmitModule, ChannelEmitKind, ChannelSlice, ChannelInspectGroup, ChannelInspectChannel, ChannelInspectWindow, ChannelInspectReport, } from "./channels.js";
 export declare const serverDataStorage: AsyncLocalStorage<Record<string, unknown>>;
 type ServerCallback = (server: import("http").Server) => void;
 export declare function onServer(fn: ServerCallback): void;