@mauroandre/velojs 0.0.25 → 0.0.26

package/README.md

@@ -534,6 +534,47 @@ The client-side transform rewrites the import to fetch `/_action/admin/Layout/lo
 
 ---
 
+## Endpoints
+
+Declarative HTTP endpoints for anything that isn't a page — webhooks, email-verification redirects, OAuth callbacks, health checks.
+
+Declare them directly in `routes.tsx`:
+
+```tsx
+import type { AppRoutes, EndpointHandler } from "@mauroandre/velojs";
+import * as Home from "./pages/Home.js";
+import { githubWebhook } from "./webhooks/github.handler.js";
+
+export default [
+    { path: "/", module: Home },
+    { path: "/api/github/webhook", method: "POST", handler: githubWebhook },
+] satisfies AppRoutes;
+```
+
+The handler gets `{ c, params, query }` and must return a `Response`:
+
+```ts
+import type { EndpointHandler } from "@mauroandre/velojs";
+
+export const githubWebhook: EndpointHandler = async ({ c }) => {
+    const body = await c.req.json();
+    // ...verify signature, process event...
+    return c.json({ ok: true });
+};
+```
+
+Endpoints inherit parent `middlewares` and can be nested inside grouping nodes. The Vite plugin strips endpoint objects (and their handler imports) from the client bundle, so server-only code never ships to the browser.
+
+Because endpoints live in `routes.tsx`, the testing toolkit sees them automatically:
+
+```ts
+const res = await app.post("/api/github/webhook", { body: {...}, headers: {...} });
+```
+
+Full documentation: [site/docs/17-endpoints.md](./site/docs/17-endpoints.md).
+
+---
+
 ## Event Streams
 
 Push real-time updates from server to client via Server-Sent Events (SSE). Live progress, notifications, metrics, log streaming, AI tokens — anything server → client.

package/dist/client.js

@@ -1,19 +1,46 @@
-import { jsx as r } from "preact/jsx-runtime";
-import { hydrate as l } from "preact";
-import { Router as p, Route as s, Switch as h } from "wouter-preact";
-const u = (e, o = !1) => e.map((t, n) => {
-  const c = t.module.Component;
-  if (!t.children)
-    return /* @__PURE__ */ r(s, { path: t.path || "", children: /* @__PURE__ */ r(c, {}) }, n);
-  const i = u(t.children, !!t.path);
-  return t.isRoot ? /* @__PURE__ */ r(h, { children: i }, n) : t.path ? /* @__PURE__ */ r(s, { path: t.path, nest: !0, children: /* @__PURE__ */ r(c, { children: /* @__PURE__ */ r(h, { children: i }) }) }, n) : /* @__PURE__ */ r(c, { children: /* @__PURE__ */ r(h, { children: i }) }, n);
-}), m = ({ routes: e }) => {
-  const o = u(e);
-  return /* @__PURE__ */ r(p, { children: o });
-}, R = (e) => {
-  const { routes: o } = e, t = document.querySelector("body");
-  t && l(/* @__PURE__ */ r(m, { routes: o }), t);
+import { jsx as e } from "preact/jsx-runtime";
+import { hydrate as p } from "preact";
+import { Router as f, Route as l, Switch as s } from "wouter-preact";
+const u = (r, i = !1) => {
+  const o = [];
+  for (let n = 0; n < r.length; n++) {
+    const t = r[n];
+    if (!t.module) {
+      if (t.children)
+        for (const d of u(t.children, i))
+          o.push(d);
+      continue;
+    }
+    const c = t.module.Component;
+    if (!t.children) {
+      o.push(
+        /* @__PURE__ */ e(l, { path: t.path || "", children: /* @__PURE__ */ e(c, {}) }, n)
+      );
+      continue;
+    }
+    const h = u(t.children, !!t.path);
+    if (t.isRoot) {
+      o.push(/* @__PURE__ */ e(s, { children: h }, n));
+      continue;
+    }
+    if (!t.path) {
+      o.push(
+        /* @__PURE__ */ e(c, { children: /* @__PURE__ */ e(s, { children: h }) }, n)
+      );
+      continue;
+    }
+    o.push(
+      /* @__PURE__ */ e(l, { path: t.path, nest: !0, children: /* @__PURE__ */ e(c, { children: /* @__PURE__ */ e(s, { children: h }) }) }, n)
+    );
+  }
+  return o;
+}, m = ({ routes: r }) => {
+  const i = u(r);
+  return /* @__PURE__ */ e(f, { children: i });
+}, C = (r) => {
+  const { routes: i } = r, o = document.querySelector("body");
+  o && p(/* @__PURE__ */ e(m, { routes: i }), o);
 };
 export {
-  R as startClient
+  C as startClient
 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { AppRoutes, RouteNode, RouteModule, LoaderArgs, ActionArgs, Metadata, } from "./types.js";
+export type { AppRoutes, RouteNode, RouteModule, LoaderArgs, ActionArgs, Metadata, HTTPMethod, EndpointHandler, EndpointHandlerArgs, } from "./types.js";
 export type { VeloConfig } from "./config.js";
 export { defineConfig } from "./config.js";
 export { Scripts, Link } from "./components.js";

package/dist/server.js

@@ -1,200 +1,257 @@
-import { jsx as p } from "preact/jsx-runtime";
-import { Hono as b } from "hono";
-import { logger as q } from "hono/logger";
+import { jsx as g } from "preact/jsx-runtime";
+import { Hono as R } from "hono";
+import { logger as b } from "hono/logger";
 import { trimTrailingSlash as T } from "hono/trailing-slash";
-import { render as A } from "preact-render-to-string";
-import { Router as R } from "wouter-preact";
+import { render as j } from "preact-render-to-string";
+import { Router as A } from "wouter-preact";
 import { AsyncLocalStorage as C } from "node:async_hooks";
-import { getAppContext as g } from "./app-context.js";
-import { flushPendingStreamRoutes as D, registerStreamHandler as I } from "./events.js";
-const v = new C();
-globalThis.__veloServerData = v;
+import { getAppContext as v } from "./app-context.js";
+import { flushPendingStreamRoutes as $, registerStreamHandler as k } from "./events.js";
+const y = new C();
+globalThis.__veloServerData = y;
 let _ = null;
-function W(e) {
+function z(e) {
   if (_) {
     e(_);
     return;
   }
-  g().serverCallbacks.push(e);
+  v().serverCallbacks.push(e);
 }
-function y(e) {
+function S(e) {
   _ = e;
-  const t = g();
+  const t = v();
   for (const s of t.serverCallbacks) s(e);
   t.serverCallbacks.length = 0;
 }
-function J(e) {
-  g().pendingRoutes.push(e);
+function Q(e) {
+  v().pendingRoutes.push(e);
 }
-const N = (e, t, s) => {
+const D = (e, t, s) => {
   if (e.req.query("_data") === "1") {
-    const a = globalThis.__veloBuildHash || void 0, r = s ? { ...s, __buildHash: a } : { __buildHash: a };
-    return e.json(r);
+    const r = globalThis.__veloBuildHash || void 0, i = s ? { ...s, __buildHash: r } : { __buildHash: r };
+    return e.json(i);
   }
-  const n = e.req.path, o = v.run(
+  const a = e.req.path, o = y.run(
     s ?? {},
-    () => A(/* @__PURE__ */ p(R, { ssrPath: n, children: t }))
+    () => j(/* @__PURE__ */ g(A, { ssrPath: a, children: t }))
   );
   if (e.header("Cache-Control", "no-cache"), !s)
     return e.html(o);
-  const c = `<script>window.__PAGE_DATA__=${JSON.stringify(
+  const n = `<script>window.__PAGE_DATA__=${JSON.stringify(
     s
   )}<\/script>`;
-  return e.html(o.replace("</head>", `${c}</head>`));
-}, O = async (e, t) => {
-  const s = t.req.param(), n = t.req.query(), o = { params: s, query: n, c: t }, c = await Promise.all(
-    e.map(async (r) => {
-      if (!r.loader) return null;
-      const d = await r.loader(o), i = r.metadata?.moduleId;
-      return i ? { moduleId: i, loaderData: d } : null;
+  return e.html(o.replace("</head>", `${n}</head>`));
+}, I = async (e, t) => {
+  const s = t.req.param(), a = t.req.query(), o = { params: s, query: a, c: t }, n = await Promise.all(
+    e.map(async (i) => {
+      if (!i.loader) return null;
+      const l = await i.loader(o), c = i.metadata?.moduleId;
+      return c ? { moduleId: c, loaderData: l } : null;
     })
-  ), a = {
+  ), r = {
     __params: s,
-    __query: n,
+    __query: a,
     __pathname: t.req.path
   };
-  for (const r of c)
-    r && (a[r.moduleId] = r.loaderData);
+  for (const i of n)
+    i && (r[i.moduleId] = i.loaderData);
   return {
-    components: e.map((r) => r.Component),
-    data: a
+    components: e.map((i) => i.Component),
+    data: r
   };
-}, j = (e) => {
+}, N = (e) => {
   if (e.length === 0) return null;
   const t = e.filter(Boolean);
   if (t.length === 0) return null;
   if (t.length === 1) {
     const o = t[0];
-    return /* @__PURE__ */ p(o, {});
+    return /* @__PURE__ */ g(o, {});
   }
   const s = t[t.length - 1];
-  return t.slice(0, -1).reduceRight((o, c) => /* @__PURE__ */ p(c, { children: o }), /* @__PURE__ */ p(s, {}));
-}, w = (e, t, s = [], n = []) => {
+  return t.slice(0, -1).reduceRight((o, n) => /* @__PURE__ */ g(n, { children: o }), /* @__PURE__ */ g(s, {}));
+}, w = (e, t, s = [], a = []) => {
   for (const o of t) {
-    const c = [...s, o.module], a = [
-      ...n,
+    if (o.handler && !o.module) {
+      o.children && w(
+        e,
+        o.children,
+        s,
+        [...a, ...o.middlewares || []]
+      );
+      continue;
+    }
+    const n = o.module ? [...s, o.module] : s, r = [
+      ...a,
       ...o.middlewares || []
     ];
     if (o.children)
       w(
         e,
         o.children,
-        c,
-        a
+        n,
+        r
       );
-    else {
-      const r = o.module.metadata?.fullPath;
-      if (!r) {
+    else if (o.module) {
+      const i = o.module.metadata?.fullPath;
+      if (!i) {
         console.warn(
           `Module ${o.module.metadata?.moduleId} has no fullPath`
         );
         continue;
       }
-      const d = async (i) => {
-        const { components: u, data: m } = await O(c, i), l = j(u);
-        return N(i, l, m);
+      const l = async (c) => {
+        const { components: u, data: h } = await I(n, c), d = N(u);
+        return D(c, d, h);
       };
-      a.length > 0 ? e.on(["GET"], [r], ...a, d) : e.on(["GET"], [r], d);
-    }
+      r.length > 0 ? e.on(["GET"], [i], ...r, l) : e.on(["GET"], [i], l);
+    } else
+      continue;
   }
-}, S = (e, t, s = []) => {
-  for (const n of t) {
-    const o = n.module.metadata?.moduleId, c = [
+}, P = (e, t, s = []) => {
+  for (const a of t) {
+    const o = a.module?.metadata?.moduleId, n = [
       ...s,
-      ...n.middlewares || []
+      ...a.middlewares || []
     ];
-    if (o) {
-      const a = Object.keys(n.module).filter(
-        (r) => r.startsWith("action_")
+    if (a.module && o) {
+      const r = Object.keys(a.module).filter(
+        (i) => i.startsWith("action_")
       );
-      for (const r of a) {
-        const d = r.replace("action_", ""), i = n.module[r];
-        if (typeof i == "function") {
-          const u = `/_action/${o}/${d}`, m = async (l) => {
-            let f = {};
+      for (const i of r) {
+        const l = i.replace("action_", ""), c = a.module[i];
+        if (typeof c == "function") {
+          const u = `/_action/${o}/${l}`, h = async (d) => {
+            let m = {};
             try {
-              f = await l.req.json();
+              m = await d.req.json();
             } catch {
             }
-            const P = {
-              body: f,
-              params: l.req.param(),
-              query: l.req.query(),
-              c: l
+            const f = {
+              body: m,
+              params: d.req.param(),
+              query: d.req.query(),
+              c: d
             };
             try {
-              const h = await i(P);
-              return l.json(h ?? { ok: !0 });
-            } catch (h) {
-              const E = h instanceof Error ? h.message : "Action failed";
-              return l.json({ error: E }, 500);
+              const p = await c(f);
+              return d.json(p ?? { ok: !0 });
+            } catch (p) {
+              const q = p instanceof Error ? p.message : "Action failed";
+              return d.json({ error: q }, 500);
             }
           };
-          c.length > 0 ? e.on(
+          n.length > 0 ? e.on(
             ["POST"],
             [u],
-            ...c,
-            m
-          ) : e.on(["POST"], [u], m);
+            ...n,
+            h
+          ) : e.on(["POST"], [u], h);
         }
       }
     }
-    n.children && S(e, n.children, c);
+    a.children && P(e, a.children, n);
   }
-}, $ = async (e, t, s = []) => {
-  const n = (o, c) => {
-    for (const a of o) {
-      const r = a.module.metadata?.moduleId, d = [
-        ...c,
-        ...a.middlewares || []
+}, O = async (e, t, s = []) => {
+  const a = (o, n) => {
+    for (const r of o) {
+      const i = r.module?.metadata?.moduleId, l = [
+        ...n,
+        ...r.middlewares || []
       ];
-      if (r) {
-        const i = Object.keys(a.module).filter(
+      if (r.module && i) {
+        const c = Object.keys(r.module).filter(
           (u) => u.startsWith("stream_")
         );
-        for (const u of i) {
-          const m = u.replace("stream_", ""), l = a.module[u];
-          if (l?.__isVeloEventStream) {
-            const f = `/_event/${r}/${m}`;
-            l.__path = f, I(
+        for (const u of c) {
+          const h = u.replace("stream_", ""), d = r.module[u];
+          if (d?.__isVeloEventStream) {
+            const m = `/_event/${i}/${h}`;
+            d.__path = m, k(
               e,
-              f,
-              l,
-              d
+              m,
+              d,
+              l
             );
           }
         }
       }
-      a.children && n(a.children, d);
+      r.children && a(r.children, l);
     }
   };
-  n(t, s);
-}, k = async (e) => {
-  const t = new b();
-  t.use(T()), process.env.NODE_ENV !== "production" && t.use("*", q());
-  const n = g().pendingRoutes.splice(0);
-  for (const o of n)
-    await o(t);
-  if (w(t, e), S(t, e), await $(t, e), D(t), process.env.NODE_ENV !== "production" && !_) {
-    const o = globalThis.__veloDevServer;
-    o && y(o);
+  a(t, s);
+}, G = (e, t) => t ? t.startsWith("/") ? e + t : e ? e + "/" + t : "/" + t : e || "", H = (e) => {
+  const t = /* @__PURE__ */ new Set(), s = (a) => {
+    for (const o of a) {
+      if (o.module && !o.children) {
+        const n = o.module.metadata?.fullPath;
+        n && t.add(n);
+      }
+      o.children && s(o.children);
+    }
+  };
+  return s(e), t;
+}, E = (e, t, s, a = "", o = []) => {
+  for (const n of t) {
+    const r = G(a, n.path), i = [
+      ...o,
+      ...n.middlewares || []
+    ], l = !!n.handler, c = !!n.method;
+    if (l && !c ? console.warn(
+      `[velojs] invalid route at "${r || "/"}" — "handler" set without "method"; endpoint skipped`
+    ) : c && !l ? console.warn(
+      `[velojs] invalid route at "${r || "/"}" — "method" set without "handler"; endpoint skipped`
+    ) : l && n.module ? console.warn(
+      `[velojs] ambiguous route at "${r || "/"}" — both "module" and "handler" set; endpoint ignored, page kept`
+    ) : l && n.isRoot && console.warn(
+      `[velojs] "isRoot" has no effect on endpoint at "${r || "/"}"; ignored`
+    ), l && c && !n.module) {
+      const h = n.method;
+      h === "GET" && s.has(r) && console.warn(
+        `[velojs] path "${r}" has both a page GET and an endpoint GET; endpoint will win. Consider renaming one.`
+      );
+      const d = n.handler, m = async (f) => await d({
+        c: f,
+        params: f.req.param(),
+        query: f.req.query()
+      });
+      i.length > 0 ? e.on([h], [r], ...i, m) : e.on([h], [r], m);
+    }
+    n.children && E(
+      e,
+      n.children,
+      s,
+      r,
+      i
+    );
+  }
+}, x = async (e) => {
+  const t = new R();
+  t.use(T()), process.env.NODE_ENV !== "production" && t.use("*", b());
+  const a = v().pendingRoutes.splice(0);
+  for (const n of a)
+    await n(t);
+  w(t, e), P(t, e), await O(t, e);
+  const o = H(e);
+  if (E(t, e, o), $(t), process.env.NODE_ENV !== "production" && !_) {
+    const n = globalThis.__veloDevServer;
+    n && S(n);
   }
   return t;
-}, z = async (e) => {
-  const { routes: t, port: s = Number(process.env.SERVER_PORT) || 3e3 } = e, n = await k(t);
+}, X = async (e) => {
+  const { routes: t, port: s = Number(process.env.SERVER_PORT) || 3e3 } = e, a = await x(t);
   if (process.env.NODE_ENV === "production" && !process.env.VELO_STATIC) {
-    const { serve: o } = await import("@hono/node-server"), { serveStatic: c } = await import("@hono/node-server/serve-static"), { join: a } = await import("node:path"), r = a(process.cwd(), "dist/client");
-    (process.env.STATIC_BASE_URL || "").startsWith("http") || n.use("/*", c({ root: r })), console.log(`Server running on http://localhost:${s}`);
-    const i = o({ fetch: n.fetch, port: s });
-    y(i);
+    const { serve: o } = await import("@hono/node-server"), { serveStatic: n } = await import("@hono/node-server/serve-static"), { join: r } = await import("node:path"), i = r(process.cwd(), "dist/client");
+    (process.env.STATIC_BASE_URL || "").startsWith("http") || a.use("/*", n({ root: i })), console.log(`Server running on http://localhost:${s}`);
+    const c = o({ fetch: a.fetch, port: s });
+    S(c);
   }
-  return n;
+  return a;
 };
 export {
-  J as addRoutes,
-  k as createApp,
-  k as default,
-  W as onServer,
-  v as serverDataStorage,
-  z as startServer
+  Q as addRoutes,
+  x as createApp,
+  x as default,
+  z as onServer,
+  y as serverDataStorage,
+  X as startServer
 };

package/dist/static.js

@@ -1,13 +1,13 @@
 import i from "node:fs";
 import a from "node:path";
-async function h(c, n = "") {
+async function d(c, n = "") {
   const e = [];
   for (const t of c) {
-    const o = t.module.metadata?.fullPath ?? "";
+    const o = t.module?.metadata?.fullPath ?? "";
     if (t.children) {
-      const s = await h(t.children, o);
+      const s = await d(t.children, o);
       e.push(...s);
-    } else {
+    } else if (t.module) {
       const s = t.module.metadata?.fullPath;
       if (!s) continue;
       const r = Object.keys(t.module).filter((l) => l.startsWith("action_"));
@@ -17,9 +17,9 @@ async function h(c, n = "") {
         const l = t.module.staticPaths;
         if (typeof l == "function") {
           const u = await l();
-          for (const d of u) {
+          for (const h of u) {
             let f = s;
-            for (const [p, m] of Object.entries(d))
+            for (const [p, m] of Object.entries(h))
               f = f.replace(`:${p}`, m);
             e.push({ fullPath: f, module: t.module });
           }
@@ -29,7 +29,8 @@ async function h(c, n = "") {
           );
       } else
         e.push({ fullPath: s, module: t.module });
-    }
+    } else
+      continue;
   }
   return e;
 }
@@ -60,7 +61,7 @@ function w(c) {
 async function j(c, n) {
   const e = a.resolve(process.cwd(), "dist");
   console.log("Generating static pages...");
-  const t = await h(n);
+  const t = await d(n);
   if (t.length === 0) {
     console.warn("No routes found for static generation.");
     return;