@harpy-js/core 0.4.7

package/src/core/hydration.ts

@@ -0,0 +1,70 @@
+import { AsyncLocalStorage } from "async_hooks";
+import * as crypto from "crypto";
+
+/**
+ * Tracks client components during SSR rendering
+ */
+
+export interface ClientComponentInstance {
+  componentPath: string;
+  componentName: string;
+  instanceId: string;
+  props: Record<string, any>;
+}
+
+export interface HydrationContext {
+  clientComponents: Map<string, ClientComponentInstance>;
+}
+
+// Global context storage for tracking client components during SSR
+export const hydrationContext = new AsyncLocalStorage<HydrationContext>();
+
+/**
+ * Generate a unique instance ID for a component
+ */
+export function generateInstanceId(componentPath: string): string {
+  return `${crypto.randomBytes(4).toString("hex")}-${Date.now()}`;
+}
+
+/**
+ * Initialize hydration context for a request
+ */
+export function initializeHydrationContext(): HydrationContext {
+  const context: HydrationContext = {
+    clientComponents: new Map(),
+  };
+  return context;
+}
+
+/**
+ * Register a client component instance during SSR
+ */
+export function registerClientComponent(
+  instance: ClientComponentInstance,
+): void {
+  const context = hydrationContext.getStore();
+  if (context) {
+    context.clientComponents.set(instance.instanceId, instance);
+  }
+}
+
+/**
+ * Get all registered client components
+ */
+export function getClientComponents(): ClientComponentInstance[] {
+  const context = hydrationContext.getStore();
+  if (!context) {
+    return [];
+  }
+  return Array.from(context.clientComponents.values());
+}
+
+/**
+ * Clear hydration context
+ */
+export function clearHydrationContext(): void {
+  const context = hydrationContext.getStore();
+  if (context) {
+    context.clientComponents.clear();
+  }
+}

package/src/core/jsx.engine.ts

@@ -0,0 +1,205 @@
+import { NestFastifyApplication } from "@nestjs/platform-fastify";
+import { FastifyReply } from "fastify";
+import * as React from "react";
+import { renderToPipeableStream, renderToString } from "react-dom/server";
+import { MetaOptions, RenderOptions } from "../decorators/jsx.decorator";
+import { hydrationContext, initializeHydrationContext } from "./hydration";
+import { getChunkPath, getHydrationManifest } from "./hydration-manifest";
+import { LiveReloadController } from "./live-reload.controller";
+import { StaticAssetsController } from "./static-assets.controller";
+
+export interface JsxLayoutProps {
+  children: React.ReactNode;
+  meta?: MetaOptions;
+}
+
+export type JsxLayout = (props: JsxLayoutProps) => React.ReactElement;
+
+// Cache for component-to-chunk path mappings (loaded once at startup)
+const chunkPathCache = new Map<string, string>();
+
+// Preload hydration manifest and cache chunk paths
+function initializeChunkCache() {
+  const manifest = getHydrationManifest();
+  Object.keys(manifest).forEach((componentName) => {
+    const path = getChunkPath(componentName);
+    if (path) {
+      chunkPathCache.set(componentName, path);
+    }
+  });
+  console.log(
+    `[JSX Engine] Preloaded ${chunkPathCache.size} component chunk mappings`,
+  );
+}
+
+export function withJsxEngine(
+  app: NestFastifyApplication,
+  defaultLayout: JsxLayout,
+) {
+  const isDev = process.env.NODE_ENV !== "production";
+
+  // Initialize chunk cache at startup (O(1) lookups for all requests)
+  initializeChunkCache();
+
+  // Register live reload controllers in development mode
+  if (isDev) {
+    const httpAdapter = app.getHttpAdapter();
+    const liveReloadController = new LiveReloadController();
+    const staticAssetsController = new StaticAssetsController();
+
+    // Register routes manually
+    httpAdapter.get("/__harpy/live-reload", (req: any, reply: any) => {
+      liveReloadController.liveReload(reply);
+    });
+
+    httpAdapter.post("/__harpy/live-reload/trigger", (req: any, reply: any) => {
+      liveReloadController.notifyReload();
+      reply.send({ status: "ok" });
+    });
+
+    httpAdapter.get("/__harpy/live-reload.js", (req: any, reply: any) => {
+      staticAssetsController.liveReloadScript(reply);
+    });
+  }
+
+  // Override the render method to use the jsx engine
+  // @ts-expect-error Monkey patch to make render method use jsx
+  app.getHttpAdapter().render = async function (
+    reply: FastifyReply,
+    view: [any, RenderOptions],
+    options,
+  ) {
+    const res = reply.raw;
+
+    // Redirected, bad request or error, there is no need to render the view
+    if (reply.statusCode >= 300) {
+      res.end();
+      return;
+    }
+
+    const [component, controllerOpts] = view;
+    const layout = controllerOpts.layout ?? defaultLayout;
+
+    // Prepare options for the component
+    const props = {
+      ...options,
+    };
+
+    let meta: MetaOptions | undefined = undefined;
+    if (typeof controllerOpts.meta === "function") {
+      try {
+        meta = await controllerOpts.meta(reply.request, props);
+      } catch (e) {
+        console.error("Error resolving dynamic meta:", e);
+      }
+    } else {
+      meta = controllerOpts.meta;
+    }
+
+    // Inject meta into layout props
+    const layoutProps = {
+      ...props,
+      meta,
+    };
+
+    let html: React.ReactElement;
+    if (layout) {
+      layoutProps.children = React.createElement(component, props);
+      html = React.createElement(layout, layoutProps);
+    } else {
+      html = React.createElement(component, props);
+    }
+
+    // Initialize hydration context for this request
+    const hydrationCtx = initializeHydrationContext();
+
+    // Set up component registry for client component wrapping
+    global.__COMPONENT_REGISTRY__ = (data) => {
+      hydrationCtx.clientComponents.set(data.instanceId, data);
+    };
+
+    // Single pass: render to string to collect which components are used
+    // This renders the component tree and populates hydrationCtx with registered components
+    const startTime = Date.now();
+    let htmlString = "";
+
+    hydrationContext.run(hydrationCtx, () => {
+      try {
+        htmlString = renderToString(html);
+      } catch (e) {
+        console.error(
+          "[JSX Engine] Render error:",
+          (e as Error).message?.split("\n")[0],
+        );
+        throw e;
+      }
+    });
+
+    // Extract registered components from the context
+    const registeredComponents = Array.from(
+      hydrationCtx.clientComponents.values(),
+    );
+
+    const uniqueComponentNames = new Set(
+      registeredComponents.map((c) => c.componentName),
+    );
+
+    // Use cached chunk paths (O(1) lookups)
+    const hydrationScripts = Array.from(uniqueComponentNames)
+      .map((componentName) => {
+        const path = chunkPathCache.get(componentName);
+        if (!path) {
+          // Fallback to live lookup if not in cache (shouldn't happen in production)
+          const livePath = getChunkPath(componentName);
+          if (livePath) {
+            chunkPathCache.set(componentName, livePath);
+            return { componentName, path: livePath };
+          }
+          return null;
+        }
+        return { componentName, path };
+      })
+      .filter((script) => script !== null) as Array<{
+      componentName: string;
+      path: string;
+    }>;
+
+    const renderTime = Date.now() - startTime;
+    if (isDev) {
+      console.log(
+        `[JSX Engine] Rendered in ${renderTime}ms with ${hydrationScripts.length} scripts for:`,
+        Array.from(uniqueComponentNames).join(", "),
+      );
+    }
+
+    // Build hydration scripts HTML (vendor bundle + component chunks)
+    let hydrationScriptsHtml = "";
+    if (hydrationScripts.length > 0) {
+      // Always load vendor bundle first (contains React + ReactDOM)
+      hydrationScriptsHtml = '<script src="/chunks/vendor.js"></script>';
+      // Then load component-specific chunks
+      hydrationScripts.forEach((script) => {
+        hydrationScriptsHtml += `<script src="${script.path}"></script>`;
+      });
+    }
+
+    // Inject scripts before closing body tag
+    if (isDev) {
+      // In development, add live reload script
+      const liveReloadScript =
+        '<script src="/__harpy/live-reload.js"></script>';
+      const scriptsToInject = `${hydrationScriptsHtml}${liveReloadScript}`;
+      htmlString = htmlString.replace("</body>", `${scriptsToInject}</body>`);
+    } else if (hydrationScriptsHtml) {
+      // In production, only inject hydration scripts
+      htmlString = htmlString.replace(
+        "</body>",
+        `${hydrationScriptsHtml}</body>`,
+      );
+    }
+
+    res.setHeader("content-type", "text/html");
+    reply.status(reply.statusCode || 200);
+    res.end(htmlString);
+  };
+}

package/src/core/live-reload-client.js

@@ -0,0 +1,32 @@
+/**
+ * Harpy Live Reload Client
+ * Connects to the dev server via SSE and reloads the page when changes are detected
+ */
+(function () {
+  if (typeof window === "undefined") return;
+
+  const eventSource = new EventSource("/__harpy/live-reload");
+
+  eventSource.onmessage = (event) => {
+    try {
+      const data = JSON.parse(event.data);
+      if (data.type === "reload") {
+        console.log("[Harpy] Reloading page...");
+        window.location.reload();
+      } else if (data.type === "connected") {
+        console.log("[Harpy] Live reload connected");
+      }
+    } catch (err) {
+      console.error("[Harpy] Failed to parse message:", err);
+    }
+  };
+
+  eventSource.onerror = () => {
+    console.log("[Harpy] Live reload disconnected, retrying...");
+    eventSource.close();
+    // Retry connection after 1 second
+    setTimeout(() => {
+      window.location.reload();
+    }, 1000);
+  };
+})();

package/src/core/live-reload.controller.ts

@@ -0,0 +1,55 @@
+import { FastifyReply } from "fastify";
+
+/**
+ * Live Reload Controller - Provides SSE endpoint for development hot-reload
+ * Only active in development mode
+ */
+export class LiveReloadController {
+  private clients: FastifyReply[] = [];
+  private lastReloadTime = Date.now();
+
+  liveReload(reply: FastifyReply): void {
+    // Set headers for SSE
+    reply.raw.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    });
+
+    // Add client to list
+    this.clients.push(reply);
+
+    // Send initial connection message
+    reply.raw.write(`data: ${JSON.stringify({ type: "connected" })}\n\n`);
+
+    // Remove client on close
+    reply.raw.on("close", () => {
+      const index = this.clients.indexOf(reply);
+      if (index !== -1) {
+        this.clients.splice(index, 1);
+      }
+    });
+  }
+
+  /**
+   * Notify all connected clients to reload
+   * This should be called when assets are rebuilt
+   */
+  triggerReload(): { success: boolean } {
+    this.notifyReload();
+    return { success: true };
+  }
+
+  public notifyReload() {
+    this.lastReloadTime = Date.now();
+    const message = `data: ${JSON.stringify({ type: "reload", timestamp: this.lastReloadTime })}\n\n`;
+
+    this.clients.forEach((client) => {
+      try {
+        client.raw.write(message);
+      } catch (err) {
+        // Client disconnected
+      }
+    });
+  }
+}

package/src/core/navigation.service.ts

@@ -0,0 +1,257 @@
+import { Injectable } from "@nestjs/common";
+import type {
+  NavItem,
+  NavSection,
+  NavigationRegistry,
+} from "./types/nav.types";
+
+/**
+ * Shared navigation service for registering documentation sections and items.
+ * This service is intended to be provided by the core RouterModule so feature
+ * modules can register their routes during module initialization.
+ */
+@Injectable()
+export class NavigationService implements NavigationRegistry {
+  private sections: Map<string, NavSection> = new Map();
+  // Items registered without a section are kept here and surfaced as an
+  // implicit, top-level section by `getAllSections()`.
+  private topLevelItems: NavItem[] = [];
+  // Cached, sorted snapshot of sections (shallow copies). Rebuilt when
+  // registrations change. Use `dirty` to mark the cache stale.
+  private cachedSections: NavSection[] | null = null;
+  private dirty = true;
+  // Map of normalized href -> array of { sectionId?, itemId }
+  private hrefIndex: Map<
+    string,
+    Array<{ sectionId?: string; itemId: string }>
+  > = new Map();
+
+  constructor() {}
+
+  registerSection(section: NavSection): void {
+    this.sections.set(section.id, section);
+  }
+
+  addItemToSection(sectionId: string, item: NavItem): void {
+    let section = this.sections.get(sectionId);
+    if (!section) {
+      // Lazily create the section if it doesn't exist. This keeps the core
+      // package minimal by default while allowing feature modules to add
+      // routes without needing to pre-register sections.
+      const humanize = (id: string) =>
+        id.replace(/[-_/]+/g, " ").replace(/(^|\s)\S/g, (s) => s.toUpperCase());
+
+      section = {
+        id: sectionId,
+        title: humanize(sectionId),
+        items: [],
+        // preserve undefined order by default
+      };
+      this.registerSection(section);
+    }
+
+    section.items.push(item);
+    // preserve raw insertion order in the array; sorting is applied when
+    // callers request `getAllSections()` so we can compute ordering on demand.
+  }
+
+  registerItem(item: NavItem): void {
+    this.topLevelItems.push(item);
+    this.dirty = true;
+  }
+
+  getAllSections(): NavSection[] {
+    // Return cached snapshot when available to avoid repeated sorting and
+    // object allocations. Rebuild only when registrations changed.
+    if (!this.dirty && this.cachedSections) {
+      return this.cachedSections.map((s) => ({ ...s, items: s.items.slice() }));
+    }
+
+    // Build an ordered list of sections. If there are any top-level items
+    // (items registered without a section) surface them as an implicit
+    // top-level section. That implicit section is placed before other
+    // sections by using a very low ordering value so unsectioned items
+    // appear first by default.
+    const sectionsList: NavSection[] = Array.from(this.sections.values());
+    if (this.topLevelItems.length > 0) {
+      sectionsList.unshift({
+        id: "__top__",
+        title: "",
+        items: this.topLevelItems.slice(),
+      });
+    }
+
+    const arr = sectionsList.map((s, idx) => ({
+      section: s,
+      idx,
+      order:
+        s.id === "__top__"
+          ? Number.NEGATIVE_INFINITY
+          : typeof s.order === "number"
+            ? s.order
+            : Number.POSITIVE_INFINITY,
+    }));
+
+    arr.sort((a, b) => {
+      if (a.order === b.order) return a.idx - b.idx;
+      return a.order - b.order;
+    });
+
+    // For each section, return a copy where the items are sorted by their
+    // optional `order` (lowest first) and then by insertion index.
+    const built = arr.map((x) => {
+      const s = x.section;
+
+      const itemsWithMeta = s.items.map((it, i) => ({
+        item: it,
+        idx: i,
+        order:
+          typeof it.order === "number" ? it.order : Number.POSITIVE_INFINITY,
+      }));
+
+      itemsWithMeta.sort((u, v) => {
+        if (u.order === v.order) return u.idx - v.idx;
+        return u.order - v.order;
+      });
+
+      return {
+        id: s.id,
+        title: s.title,
+        order: s.order,
+        items: itemsWithMeta.map((m) => m.item),
+      } as NavSection;
+    });
+
+    // Rebuild href index for fast active lookup.
+    this.hrefIndex.clear();
+    const normalize = (p?: string) => {
+      if (!p) return "";
+      const withoutQuery = p.split(/[?#]/)[0];
+      if (withoutQuery.length > 1 && withoutQuery.endsWith("/"))
+        return withoutQuery.slice(0, -1);
+      return withoutQuery;
+    };
+
+    for (const s of built) {
+      for (const it of s.items) {
+        if (!it.href) continue;
+        const key = normalize(it.href);
+        if (!this.hrefIndex.has(key)) this.hrefIndex.set(key, []);
+        this.hrefIndex
+          .get(key)!
+          .push({
+            sectionId: s.id === "__top__" ? undefined : s.id,
+            itemId: it.id,
+          });
+      }
+    }
+
+    this.cachedSections = built;
+    this.dirty = false;
+    // Return shallow clones so callers cannot mutate the internal cache.
+    return built.map((s) => ({ ...s, items: s.items.slice() }));
+  }
+
+  private ensureCache(): void {
+    if (this.dirty) this.getAllSections();
+  }
+
+  /**
+   * Fast active-item resolution using the prebuilt `hrefIndex`. This
+   * performs ancestor matching by trimming path segments and checking the
+   * index for the longest matching prefix. Returns the first registered
+   * item for a matched href.
+   */
+  getActiveItemId(currentPath?: string): string | undefined {
+    if (!currentPath) return undefined;
+    this.ensureCache();
+    const normalize = (p?: string) => {
+      if (!p) return "";
+      const withoutQuery = p.split(/[?#]/)[0];
+      if (withoutQuery.length > 1 && withoutQuery.endsWith("/"))
+        return withoutQuery.slice(0, -1);
+      return withoutQuery;
+    };
+
+    let cur = normalize(currentPath);
+    while (cur !== "") {
+      const entry = this.hrefIndex.get(cur);
+      if (entry && entry.length > 0) return entry[0].itemId;
+      const lastSlash = cur.lastIndexOf("/");
+      if (lastSlash === -1) break;
+      if (lastSlash === 0) {
+        cur = "/";
+      } else {
+        cur = cur.slice(0, lastSlash);
+      }
+      if (cur === "/") {
+        const entryRoot = this.hrefIndex.get("/");
+        if (entryRoot && entryRoot.length > 0) return entryRoot[0].itemId;
+        break;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Return sections where each item's `active` flag is computed against
+   * `currentPath`. This does not mutate the registered items — it returns
+   * shallow copies suitable for rendering.
+   */
+  getSectionsForRoute(currentPath?: string): NavSection[] {
+    const normalize = (p?: string) => {
+      if (!p) return "";
+      const withoutQuery = p.split(/[?#]/)[0];
+      // strip trailing slash except for root
+      if (withoutQuery.length > 1 && withoutQuery.endsWith("/")) {
+        return withoutQuery.slice(0, -1);
+      }
+      return withoutQuery;
+    };
+
+    const matches = (itemHref: string | undefined, cur: string | undefined) => {
+      if (!itemHref || !cur) return false;
+      const a = normalize(itemHref);
+      const b = normalize(cur);
+      if (!a) return false;
+      if (a === b) return true;
+      // treat an item as active when the current path is a descendant of the
+      // item's href (e.g. `/docs` matches `/docs/getting-started`).
+      return b.startsWith(a + "/");
+    };
+
+    const base = this.getAllSections();
+    if (!currentPath) return base;
+
+    // Fast path: find the single active item id and mark only that item.
+    const activeId = this.getActiveItemId(currentPath);
+    if (!activeId) return base;
+
+    return base.map((s) => ({
+      ...s,
+      items: s.items.map((it) => ({ ...it, active: it.id === activeId })),
+    }));
+  }
+
+  getSection(sectionId: string): NavSection | undefined {
+    return this.sections.get(sectionId);
+  }
+
+  /**
+   * Move an already-registered section to the front of the navigation.
+   * Useful when ordering must be adjusted after other modules have registered.
+   */
+  moveSectionToFront(sectionId: string): void {
+    const sec = this.sections.get(sectionId);
+    if (!sec) return;
+
+    const newMap = new Map<string, NavSection>();
+    newMap.set(sectionId, sec);
+    for (const [k, v] of this.sections.entries()) {
+      if (k === sectionId) continue;
+      newMap.set(k, v);
+    }
+    this.sections = newMap;
+  }
+}

package/src/core/router.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from "@nestjs/common";
+import { NavigationService } from "./navigation.service";
+
+@Global()
+@Module({
+  providers: [NavigationService],
+  exports: [NavigationService],
+})
+export class RouterModule {}

package/src/core/static-assets.controller.ts

@@ -0,0 +1,19 @@
+import { FastifyReply } from "fastify";
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * Static Assets Controller - Serves framework assets like live-reload client
+ */
+export class StaticAssetsController {
+  liveReloadScript(reply: FastifyReply): void {
+    const scriptPath = path.join(__dirname, "live-reload-client.js");
+
+    if (fs.existsSync(scriptPath)) {
+      const script = fs.readFileSync(scriptPath, "utf-8");
+      reply.type("application/javascript").send(script);
+    } else {
+      reply.code(404).send("Live reload script not found");
+    }
+  }
+}

package/src/core/types/nav.types.ts

@@ -0,0 +1,53 @@
+export interface NavItem {
+  id: string;
+  title: string;
+  href?: string;
+  /**
+   * Runtime-only hint indicating whether this item is currently active.
+   * Consumers may inspect this flag when rendering navigation UI. The
+   * navigation service exposes helpers to compute active state from the
+   * current route instead of mutating the registered items directly.
+   */
+  active?: boolean;
+  /**
+   * Optional numeric priority within a section. Lower numbers appear earlier.
+   * If omitted, registration order is used as a tiebreaker.
+   */
+  order?: number;
+}
+
+export interface NavSection {
+  id: string;
+  title: string;
+  items: NavItem[];
+  /**
+   * Optional numeric order. Lower numbers appear earlier in navigation.
+   * If omitted, insertion order is used as a tiebreaker.
+   */
+  order?: number;
+}
+
+// Minimal interface describing the navigation service surface used by feature modules.
+export interface NavigationRegistry {
+  registerSection(section: NavSection): void;
+  addItemToSection(sectionId: string, item: NavItem): void;
+  /**
+   * Register a navigation item that does not belong to any section.
+   * These items will be surfaced in a top-level, implicit section in
+   * the results returned by `getAllSections()`.
+   */
+  registerItem(item: NavItem): void;
+  /**
+   * Get all sections with items marked according to the provided route.
+   * If `currentPath` is omitted, this behaves the same as `getAllSections()`.
+   */
+  getSectionsForRoute(currentPath?: string): NavSection[];
+  /**
+   * Fast lookup for the active item's id for a given route. This is intended
+   * to be an inexpensive alternative to returning full sections with active
+   * flags when clients prefer to compute or sync active state themselves.
+   */
+  getActiveItemId(currentPath?: string): string | undefined;
+  getAllSections(): NavSection[];
+  getSection(sectionId: string): NavSection | undefined;
+}