npm - @richie-router/server - Versions diffs - 0.1.3 → 0.1.5 - Mend

@richie-router/server 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/esm/index.test.mjs ADDED Viewed

@@ -0,0 +1,335 @@
+// packages/server/src/index.test.ts
+import { describe, expect, test } from "bun:test";
+import { defineRouterSchema, redirect, createRouteNode } from "@richie-router/core";
+import { defineHeadTags, handleHeadRequest, handleHeadTagRequest, handleRequest, handleSpaRequest, matchesSpaPath } from "./index.mjs";
+function createTestArtifacts(options) {
+  const rootRoute = createRouteNode("__root__", {}, { isRoot: true });
+  const indexRoute = createRouteNode("/", {});
+  const authRoute = createRouteNode("/_auth", {});
+  const authDashboardRoute = createRouteNode("/_auth/dashboard", {});
+  const aboutRoute = createRouteNode("/about", {});
+  const postsRoute = createRouteNode("/posts", {});
+  const postsIndexRoute = createRouteNode("/posts/", {});
+  const postsPostIdRoute = createRouteNode("/posts/$postId", {});
+  aboutRoute._setServerHead(true);
+  authRoute._addFileChildren({
+    dashboard: authDashboardRoute
+  });
+  postsRoute._addFileChildren({
+    index: postsIndexRoute,
+    postId: postsPostIdRoute
+  });
+  rootRoute._addFileChildren({
+    index: indexRoute,
+    auth: authRoute,
+    about: aboutRoute,
+    posts: postsRoute
+  });
+  const routerSchema = defineRouterSchema({
+    "/about": {
+      serverHead: true
+    }
+  });
+  const headTags = defineHeadTags(rootRoute, routerSchema, {
+    "/about": {
+      staleTime: options?.aboutStaleTime,
+      head: () => {
+        if (options?.redirectAbout) {
+          redirect({ to: "/" });
+        }
+        return [
+          { tag: "title", children: "About" },
+          ...options?.customHeadElement ? [{
+            tag: "link",
+            rel: "icon",
+            href: "/favicon.ico",
+            sizes: "any"
+          }] : []
+        ];
+      }
+    }
+  });
+  return {
+    routeManifest: rootRoute,
+    headTags,
+    spaRoutesManifest: {
+      routes: [
+        { id: "__root__", to: "/", parentId: null, isRoot: true },
+        { id: "/", to: "/", parentId: "__root__", isRoot: false },
+        { id: "/_auth", to: "/", parentId: "__root__", isRoot: false },
+        { id: "/_auth/dashboard", to: "/dashboard", parentId: "/_auth", isRoot: false },
+        { id: "/about", to: "/about", parentId: "__root__", isRoot: false },
+        { id: "/posts", to: "/posts", parentId: "__root__", isRoot: false },
+        { id: "/posts/", to: "/posts", parentId: "/posts", isRoot: false },
+        { id: "/posts/$postId", to: "/posts/$postId", parentId: "/posts", isRoot: false }
+      ],
+      spaRoutes: ["/", "/about", "/dashboard", "/posts", "/posts/$postId"]
+    }
+  };
+}
+describe("handleSpaRequest", () => {
+  test("exposes a pure SPA matcher for host-side routing decisions", () => {
+    const { spaRoutesManifest, routeManifest } = createTestArtifacts();
+    expect(matchesSpaPath("/project/about", {
+      spaRoutesManifest,
+      basePath: "/project"
+    })).toBe(true);
+    expect(matchesSpaPath("/project/posts/123", {
+      routeManifest,
+      basePath: "/project"
+    })).toBe(true);
+    expect(matchesSpaPath("/project/api/health", {
+      spaRoutesManifest,
+      basePath: "/project"
+    })).toBe(false);
+  });
+  test("matches document requests under the basePath with a routeManifest", async () => {
+    const { routeManifest } = createTestArtifacts();
+    const result = await handleSpaRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      basePath: "/project",
+      headers: {
+        "cache-control": "no-cache"
+      },
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+    const html = await result.response.text();
+    expect(html).not.toContain("window.__RICHIE_ROUTER_HEAD__");
+    expect(html).toContain('<div id="app"></div>');
+    expect(result.response.headers.get("cache-control")).toBe("no-cache");
+  });
+  test("matches document requests under the basePath with a spaRoutesManifest", async () => {
+    const { spaRoutesManifest } = createTestArtifacts();
+    const result = await handleSpaRequest(new Request("https://example.com/project/about"), {
+      spaRoutesManifest,
+      basePath: "/project",
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+  });
+  test("does not match sibling paths that only share the same prefix", async () => {
+    const { spaRoutesManifest } = createTestArtifacts();
+    const result = await handleSpaRequest(new Request("https://example.com/projectish/about"), {
+      spaRoutesManifest,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    expect(result.matched).toBe(false);
+    expect(result.response.status).toBe(404);
+  });
+  test("matches dynamic and pathless-derived public routes from a spaRoutesManifest", async () => {
+    const { spaRoutesManifest } = createTestArtifacts();
+    for (const pathname of ["/project/dashboard", "/project/posts/123"]) {
+      const result = await handleSpaRequest(new Request(`https://example.com${pathname}`), {
+        spaRoutesManifest,
+        basePath: "/project",
+        html: {
+          template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+        }
+      });
+      expect(result.matched).toBe(true);
+      expect(result.response.status).toBe(200);
+    }
+  });
+  test("allows string templates without the head placeholder", async () => {
+    const { routeManifest } = createTestArtifacts();
+    const result = await handleSpaRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      basePath: "/project",
+      html: {
+        template: '<html><head></head><body><div id="app"></div></body></html>'
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(await result.response.text()).toContain('<div id="app"></div>');
+  });
+});
+describe("handleRequest basePath", () => {
+  test("matches document requests under the basePath", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await handleRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+    const html = await result.response.text();
+    expect(html).toContain("About</title>");
+    expect(html).toContain('<div id="app"></div>');
+  });
+  test("does not match sibling paths that only share the same prefix", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await handleRequest(new Request("https://example.com/projectish/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    expect(result.matched).toBe(false);
+    expect(result.response.status).toBe(404);
+  });
+  test("prefixes redirects with the basePath", async () => {
+    const { routeManifest, headTags } = createTestArtifacts({
+      redirectAbout: true
+    });
+    const result = await handleRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(302);
+    expect(result.response.headers.get("location")).toBe("/project");
+  });
+  test("uses the basePath for default head API requests handled through handleRequest", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await handleRequest(new Request("https://example.com/project/head-api?routeId=%2Fabout&params=%7B%7D&search=%7B%7D"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+    expect(await result.response.json()).toEqual({
+      head: [
+        { tag: "title", children: "About" }
+      ]
+    });
+  });
+  test("allows direct head tag handling with basePath shorthand", async () => {
+    const { headTags } = createTestArtifacts();
+    const result = await handleHeadTagRequest(new Request("https://example.com/project/head-api?routeId=%2Fabout&params=%7B%7D&search=%7B%7D"), {
+      headTags,
+      basePath: "/project"
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+    expect(await result.response.json()).toEqual({
+      head: [
+        { tag: "title", children: "About" }
+      ]
+    });
+  });
+  test("resolves merged document head payloads for host-rendered HTML shells", async () => {
+    const { headTags } = createTestArtifacts();
+    const result = await handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+    const payload = await result.response.json();
+    expect(payload.href).toBe("/about");
+    expect(payload.head).toEqual([
+      { tag: "title", children: "About" }
+    ]);
+    expect(payload.routeHeads).toEqual([
+      {
+        routeId: "/about",
+        head: [
+          { tag: "title", children: "About" }
+        ]
+      }
+    ]);
+    expect(payload.richieRouterHead).toContain("About</title>");
+    expect(payload.richieRouterHead).toContain("window.__RICHIE_ROUTER_HEAD__");
+    expect(result.response.headers.get("cache-control")).toBe("private, no-store");
+  });
+  test("returns redirect responses for document head payload requests", async () => {
+    const { headTags } = createTestArtifacts({
+      redirectAbout: true
+    });
+    const result = await handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(302);
+    expect(result.response.headers.get("location")).toBe("/project");
+  });
+  test("serializes custom head elements for rich host templates", async () => {
+    const { headTags } = createTestArtifacts({
+      customHeadElement: true
+    });
+    const result = await handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    const payload = await result.response.json();
+    expect(payload.richieRouterHead).toContain('<link rel="icon" href="/favicon.ico" sizes="any" data-richie-router-head="true">');
+  });
+  test("derives cache-control headers from route staleTime", async () => {
+    const { headTags } = createTestArtifacts({
+      aboutStaleTime: 60000
+    });
+    const result = await handleHeadRequest(new Request("https://example.com/project/head-api?routeId=%2Fabout&params=%7B%7D&search=%7B%7D"), {
+      headTags,
+      basePath: "/project"
+    });
+    expect(result.response.headers.get("cache-control")).toBe("private, max-age=60");
+    expect(await result.response.json()).toEqual({
+      head: [
+        { tag: "title", children: "About" }
+      ],
+      staleTime: 60000
+    });
+  });
+  test("derives document cache-control headers from the matched staleTime", async () => {
+    const { headTags } = createTestArtifacts({
+      aboutStaleTime: 5000
+    });
+    const result = await handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    expect(result.response.headers.get("cache-control")).toBe("private, max-age=5");
+    const payload = await result.response.json();
+    expect(payload.staleTime).toBe(5000);
+    expect(payload.routeHeads).toEqual([
+      {
+        routeId: "/about",
+        head: [
+          { tag: "title", children: "About" }
+        ],
+        staleTime: 5000
+      }
+    ]);
+  });
+  test("preserves custom headers on successful document responses", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await handleRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      headers: {
+        "cache-control": "no-cache"
+      },
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.headers.get("cache-control")).toBe("no-cache");
+  });
+});

package/dist/types/index.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { type ResolveAllParamsForRouteId, type RouteIdsWithServerHead, type RouterSchemaShape, type InferRouterSearchSchema, type AnyRoute, type HeadConfig } from '@richie-router/core';
+import { type ResolveAllParamsForRouteId, type RouteIdsWithServerHead, type RouterSchemaShape, type InferRouterSearchSchema, type AnyRoute, type HeadConfig, type RouteHeadEntry } from '@richie-router/core';
 export interface HeadTagContext<TParams extends Record<string, string>, TSearch> {
     request: Request;
     params: TParams;
@@ -24,20 +24,58 @@ export interface HtmlOptions {
         head: HeadConfig;
     }) => string | Promise<string>);
 }
+export interface SpaRoutesManifestRoute {
+    id: string;
+    to: string;
+    parentId: string | null;
+    isRoot: boolean;
+}
+export interface SpaRoutesManifest {
+    routes?: SpaRoutesManifestRoute[];
+    spaRoutes: string[];
+}
+interface BaseMatchSpaPathOptions {
+    basePath?: string;
+}
+export type MatchSpaPathOptions = ({
+    routeManifest: AnyRoute;
+} & BaseMatchSpaPathOptions) | ({
+    spaRoutesManifest: SpaRoutesManifest;
+} & BaseMatchSpaPathOptions);
+interface DocumentResponseOptions {
+    html: HtmlOptions;
+    headers?: HeadersInit;
+}
+export type HandleSpaRequestOptions = MatchSpaPathOptions & DocumentResponseOptions;
 export interface HandleRequestOptions<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape> {
     routeManifest: TRouteManifest;
     headTags: DefinedHeadTags<TRouteManifest, TRouterSchema>;
     html: HtmlOptions;
+    basePath?: string;
+    headers?: HeadersInit;
     headBasePath?: string;
-    routeBasePath?: string;
 }
 export interface HandleHeadTagRequestOptions<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape> {
     headTags: DefinedHeadTags<TRouteManifest, TRouterSchema>;
+    basePath?: string;
     headBasePath?: string;
 }
 export interface HandleRequestResult {
     matched: boolean;
     response: Response;
 }
+export interface RouteHeadResponsePayload {
+    head: HeadConfig;
+    staleTime?: number;
+}
+export interface DocumentHeadResponsePayload extends RouteHeadResponsePayload {
+    href: string;
+    richieRouterHead: string;
+    routeHeads: RouteHeadEntry[];
+}
+export declare function matchesSpaPath(path: string, options: MatchSpaPathOptions): boolean;
+export declare function handleHeadRequest<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape>(request: Request, options: HandleHeadTagRequestOptions<TRouteManifest, TRouterSchema>): Promise<HandleRequestResult>;
 export declare function handleHeadTagRequest<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape>(request: Request, options: HandleHeadTagRequestOptions<TRouteManifest, TRouterSchema>): Promise<HandleRequestResult>;
+export declare function handleSpaRequest(request: Request, options: HandleSpaRequestOptions): Promise<HandleRequestResult>;
 export declare function handleRequest<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape>(request: Request, options: HandleRequestOptions<TRouteManifest, TRouterSchema>): Promise<HandleRequestResult>;
+export {};

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@richie-router/server",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Server helpers for Richie Router head tags and document handling",
   "sideEffects": false,
   "exports": {
@@ -13,7 +13,7 @@
     }
   },
   "dependencies": {
-    "@richie-router/core": "^0.1.2"
+    "@richie-router/core": "^0.1.3"
   },
   "author": "Richie <oss@ricsam.dev>",
   "homepage": "https://docs.ricsam.dev/richie-router",