@richie-router/server 0.1.7 → 0.1.8

package/dist/cjs/index.cjs

@@ -40,6 +40,7 @@ var __export = (target, all) => {
 var exports_src = {};
 __export(exports_src, {
   matchesSpaPath: () => matchesSpaPath,
+  matchesPassthroughPath: () => matchesPassthroughPath,
   handleSpaRequest: () => handleSpaRequest,
   handleRequest: () => handleRequest,
   handleHeadTagRequest: () => handleHeadTagRequest,
@@ -236,6 +237,15 @@ function resolveSpaRoutes(spaRoutesManifest) {
   }
   return spaRoutes;
 }
+function resolveHostedRouting(options) {
+  if ("routeManifest" in options) {
+    return import_core.resolveHostedRoutingConfig(options.routeManifest.hostedRouting);
+  }
+  return import_core.resolveHostedRoutingConfig(options.spaRoutesManifest.hostedRouting);
+}
+function matchesPassthroughLocation(options, location) {
+  return resolveHostedRouting(options).passthrough.some((route) => import_core.matchPathname(route, location.pathname) !== null);
+}
 function matchesSpaLocation(options, location) {
   if ("routeManifest" in options) {
     return buildMatches(options.routeManifest, location).length > 0;
@@ -249,9 +259,16 @@ function matchesSpaPath(path, options) {
   }
   return matchesSpaLocation(options, documentRequest.location);
 }
+function matchesPassthroughPath(path, options) {
+  const documentRequest = resolveDocumentPath(path, options.basePath);
+  if (documentRequest === null) {
+    return false;
+  }
+  return matchesPassthroughLocation(options, documentRequest.location);
+}
 async function executeHeadTag(request, headTags, routeId, params, rawSearch) {
   const definition = headTags.definitions[routeId];
-  const schemaEntry = headTags.routerSchema[routeId];
+  const schemaEntry = import_core.getRouteSchemaEntry(headTags.routerSchema, routeId);
   if (!definition) {
     throw new Error(`Unknown server head route "${routeId}".`);
   }
@@ -372,7 +389,7 @@ async function handleDocumentHeadRequest(request, options, href) {
 async function handleHeadRequest(request, options) {
   const url = new URL(request.url);
   const basePath = normalizeBasePath(options.basePath);
-  const headBasePath = options.headBasePath ?? prependBasePathToPathname("/head-api", basePath);
+  const headBasePath = prependBasePathToPathname(import_core.getRouterSchemaHostedRouting(options.headTags.routerSchema).headBasePath, basePath);
   if (url.pathname !== headBasePath) {
     return {
       matched: false,
@@ -445,8 +462,7 @@ async function handleRequest(request, options) {
   const basePath = normalizeBasePath(options.basePath);
   const handledHeadTagRequest = await handleHeadTagRequest(request, {
     headTags: options.headTags,
-    basePath,
-    headBasePath: options.headBasePath
+    basePath
   });
   if (handledHeadTagRequest.matched) {
     return handledHeadTagRequest;

package/dist/cjs/index.test.cjs

@@ -29,6 +29,9 @@ function createTestArtifacts(options) {
     "/about": {
       serverHead: true
     }
+  }, {
+    passthrough: ["/api/$"],
+    headBasePath: options?.headBasePath
   });
   const headTags = import__.defineHeadTags(rootRoute, routerSchema, {
     "/about": {
@@ -49,6 +52,10 @@ function createTestArtifacts(options) {
       }
     }
   });
+  rootRoute._setHostedRouting({
+    headBasePath: options?.headBasePath ?? "/head-api",
+    passthrough: [options?.headBasePath ?? "/head-api", "/api/$"]
+  });
   return {
     routeManifest: rootRoute,
     headTags,
@@ -63,7 +70,11 @@ function createTestArtifacts(options) {
         { id: "/posts/", to: "/posts", parentId: "/posts", isRoot: false },
         { id: "/posts/$postId", to: "/posts/$postId", parentId: "/posts", isRoot: false }
       ],
-      spaRoutes: ["/", "/about", "/dashboard", "/posts", "/posts/$postId"]
+      spaRoutes: ["/", "/about", "/dashboard", "/posts", "/posts/$postId"],
+      hostedRouting: {
+        headBasePath: options?.headBasePath ?? "/head-api",
+        passthrough: [options?.headBasePath ?? "/head-api", "/api/$"]
+      }
     }
   };
 }
@@ -166,6 +177,21 @@ import_bun_test.describe("handleSpaRequest", () => {
       basePath: "/project"
     })).toBe(false);
   });
+  import_bun_test.test("exposes passthrough matching for host-side routing decisions", () => {
+    const { spaRoutesManifest, routeManifest } = createTestArtifacts();
+    import_bun_test.expect(import__.matchesPassthroughPath("/project/head-api", {
+      spaRoutesManifest,
+      basePath: "/project"
+    })).toBe(true);
+    import_bun_test.expect(import__.matchesPassthroughPath("/project/api/health", {
+      routeManifest,
+      basePath: "/project"
+    })).toBe(true);
+    import_bun_test.expect(import__.matchesPassthroughPath("/project/about", {
+      spaRoutesManifest,
+      basePath: "/project"
+    })).toBe(false);
+  });
   import_bun_test.test("matches document requests under the basePath with a routeManifest", async () => {
     const { routeManifest } = createTestArtifacts();
     const result = await import__.handleSpaRequest(new Request("https://example.com/project/about"), {
@@ -314,6 +340,22 @@ import_bun_test.describe("handleRequest basePath", () => {
       ]
     });
   });
+  import_bun_test.test("reads a custom headBasePath from the router schema", async () => {
+    const { headTags } = createTestArtifacts({
+      headBasePath: "/meta"
+    });
+    const result = await import__.handleHeadTagRequest(new Request("https://example.com/project/meta?routeId=%2Fabout&params=%7B%7D&search=%7B%7D"), {
+      headTags,
+      basePath: "/project"
+    });
+    import_bun_test.expect(result.matched).toBe(true);
+    import_bun_test.expect(result.response.status).toBe(200);
+    import_bun_test.expect(await result.response.json()).toEqual({
+      head: [
+        { tag: "title", children: "About" }
+      ]
+    });
+  });
   import_bun_test.test("resolves merged document head payloads for host-rendered HTML shells", async () => {
     const { headTags } = createTestArtifacts();
     const result = await import__.handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {

package/dist/esm/index.mjs

@@ -4,11 +4,14 @@ import {
   createParsedLocation,
   defaultParseSearch,
   defaultStringifySearch,
+  getRouteSchemaEntry,
+  getRouterSchemaHostedRouting,
   isNotFound,
   isRedirect,
   matchPathname,
   matchRouteTree,
   resolveHeadConfig,
+  resolveHostedRoutingConfig,
   serializeHeadConfig
 } from "@richie-router/core";
 function defineHeadTags(routeManifest, routerSchema, definitions) {
@@ -199,6 +202,15 @@ function resolveSpaRoutes(spaRoutesManifest) {
   }
   return spaRoutes;
 }
+function resolveHostedRouting(options) {
+  if ("routeManifest" in options) {
+    return resolveHostedRoutingConfig(options.routeManifest.hostedRouting);
+  }
+  return resolveHostedRoutingConfig(options.spaRoutesManifest.hostedRouting);
+}
+function matchesPassthroughLocation(options, location) {
+  return resolveHostedRouting(options).passthrough.some((route) => matchPathname(route, location.pathname) !== null);
+}
 function matchesSpaLocation(options, location) {
   if ("routeManifest" in options) {
     return buildMatches(options.routeManifest, location).length > 0;
@@ -212,9 +224,16 @@ function matchesSpaPath(path, options) {
   }
   return matchesSpaLocation(options, documentRequest.location);
 }
+function matchesPassthroughPath(path, options) {
+  const documentRequest = resolveDocumentPath(path, options.basePath);
+  if (documentRequest === null) {
+    return false;
+  }
+  return matchesPassthroughLocation(options, documentRequest.location);
+}
 async function executeHeadTag(request, headTags, routeId, params, rawSearch) {
   const definition = headTags.definitions[routeId];
-  const schemaEntry = headTags.routerSchema[routeId];
+  const schemaEntry = getRouteSchemaEntry(headTags.routerSchema, routeId);
   if (!definition) {
     throw new Error(`Unknown server head route "${routeId}".`);
   }
@@ -335,7 +354,7 @@ async function handleDocumentHeadRequest(request, options, href) {
 async function handleHeadRequest(request, options) {
   const url = new URL(request.url);
   const basePath = normalizeBasePath(options.basePath);
-  const headBasePath = options.headBasePath ?? prependBasePathToPathname("/head-api", basePath);
+  const headBasePath = prependBasePathToPathname(getRouterSchemaHostedRouting(options.headTags.routerSchema).headBasePath, basePath);
   if (url.pathname !== headBasePath) {
     return {
       matched: false,
@@ -408,8 +427,7 @@ async function handleRequest(request, options) {
   const basePath = normalizeBasePath(options.basePath);
   const handledHeadTagRequest = await handleHeadTagRequest(request, {
     headTags: options.headTags,
-    basePath,
-    headBasePath: options.headBasePath
+    basePath
   });
   if (handledHeadTagRequest.matched) {
     return handledHeadTagRequest;
@@ -461,6 +479,7 @@ async function handleRequest(request, options) {
 }
 export {
   matchesSpaPath,
+  matchesPassthroughPath,
   handleSpaRequest,
   handleRequest,
   handleHeadTagRequest,

package/dist/esm/index.test.mjs

@@ -1,7 +1,7 @@
 // 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";
+import { defineHeadTags, handleHeadRequest, handleHeadTagRequest, handleRequest, handleSpaRequest, matchesPassthroughPath, matchesSpaPath } from "./index.mjs";
 function createTestArtifacts(options) {
   const rootRoute = createRouteNode("__root__", {}, { isRoot: true });
   const indexRoute = createRouteNode("/", {});
@@ -29,6 +29,9 @@ function createTestArtifacts(options) {
     "/about": {
       serverHead: true
     }
+  }, {
+    passthrough: ["/api/$"],
+    headBasePath: options?.headBasePath
   });
   const headTags = defineHeadTags(rootRoute, routerSchema, {
     "/about": {
@@ -49,6 +52,10 @@ function createTestArtifacts(options) {
       }
     }
   });
+  rootRoute._setHostedRouting({
+    headBasePath: options?.headBasePath ?? "/head-api",
+    passthrough: [options?.headBasePath ?? "/head-api", "/api/$"]
+  });
   return {
     routeManifest: rootRoute,
     headTags,
@@ -63,7 +70,11 @@ function createTestArtifacts(options) {
         { id: "/posts/", to: "/posts", parentId: "/posts", isRoot: false },
         { id: "/posts/$postId", to: "/posts/$postId", parentId: "/posts", isRoot: false }
       ],
-      spaRoutes: ["/", "/about", "/dashboard", "/posts", "/posts/$postId"]
+      spaRoutes: ["/", "/about", "/dashboard", "/posts", "/posts/$postId"],
+      hostedRouting: {
+        headBasePath: options?.headBasePath ?? "/head-api",
+        passthrough: [options?.headBasePath ?? "/head-api", "/api/$"]
+      }
     }
   };
 }
@@ -166,6 +177,21 @@ describe("handleSpaRequest", () => {
       basePath: "/project"
     })).toBe(false);
   });
+  test("exposes passthrough matching for host-side routing decisions", () => {
+    const { spaRoutesManifest, routeManifest } = createTestArtifacts();
+    expect(matchesPassthroughPath("/project/head-api", {
+      spaRoutesManifest,
+      basePath: "/project"
+    })).toBe(true);
+    expect(matchesPassthroughPath("/project/api/health", {
+      routeManifest,
+      basePath: "/project"
+    })).toBe(true);
+    expect(matchesPassthroughPath("/project/about", {
+      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"), {
@@ -314,6 +340,22 @@ describe("handleRequest basePath", () => {
       ]
     });
   });
+  test("reads a custom headBasePath from the router schema", async () => {
+    const { headTags } = createTestArtifacts({
+      headBasePath: "/meta"
+    });
+    const result = await handleHeadTagRequest(new Request("https://example.com/project/meta?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"), {

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-import { type ResolveAllParamsForRouteId, type RouteIdsWithServerHead, type RouterSchemaShape, type InferRouterSearchSchema, type AnyRoute, type HeadConfig, type RouteHeadEntry } from '@richie-router/core';
+import { type ResolveAllParamsForRouteId, type RouteIdsWithServerHead, type AnyRouterSchema, type InferRouterSearchSchema, type AnyRoute, type HeadConfig, type HostedRoutingConfig, type RouteHeadEntry } from '@richie-router/core';
 export interface HeadTagContext<TParams extends Record<string, string>, TSearch> {
     request: Request;
     params: TParams;
@@ -8,15 +8,15 @@ export interface HeadTagDefinition<TParams extends Record<string, string>, TSear
     staleTime?: number;
     head: (ctx: HeadTagContext<TParams, TSearch>) => Promise<HeadConfig> | HeadConfig;
 }
-export type HeadTagDefinitions<TRouterSchema extends RouterSchemaShape> = {
+export type HeadTagDefinitions<TRouterSchema extends AnyRouterSchema> = {
     [TRouteId in RouteIdsWithServerHead<TRouterSchema>]: HeadTagDefinition<ResolveAllParamsForRouteId<TRouteId>, InferRouterSearchSchema<TRouterSchema, TRouteId>>;
 };
-export interface DefinedHeadTags<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape> {
+export interface DefinedHeadTags<TRouteManifest extends AnyRoute, TRouterSchema extends AnyRouterSchema> {
     routeManifest: TRouteManifest;
     routerSchema: TRouterSchema;
     definitions: HeadTagDefinitions<TRouterSchema>;
 }
-export declare function defineHeadTags<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape>(routeManifest: TRouteManifest, routerSchema: TRouterSchema, definitions: HeadTagDefinitions<TRouterSchema>): DefinedHeadTags<TRouteManifest, TRouterSchema>;
+export declare function defineHeadTags<TRouteManifest extends AnyRoute, TRouterSchema extends AnyRouterSchema>(routeManifest: TRouteManifest, routerSchema: TRouterSchema, definitions: HeadTagDefinitions<TRouterSchema>): DefinedHeadTags<TRouteManifest, TRouterSchema>;
 export interface HtmlOptions {
     template: string | ((ctx: {
         request: Request;
@@ -33,6 +33,7 @@ export interface SpaRoutesManifestRoute {
 export interface SpaRoutesManifest {
     routes?: SpaRoutesManifestRoute[];
     spaRoutes: string[];
+    hostedRouting?: HostedRoutingConfig;
 }
 interface BaseMatchSpaPathOptions {
     basePath?: string;
@@ -47,18 +48,16 @@ interface DocumentResponseOptions {
     headers?: HeadersInit;
 }
 export type HandleSpaRequestOptions = MatchSpaPathOptions & DocumentResponseOptions;
-export interface HandleRequestOptions<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape> {
+export interface HandleRequestOptions<TRouteManifest extends AnyRoute, TRouterSchema extends AnyRouterSchema> {
     routeManifest: TRouteManifest;
     headTags: DefinedHeadTags<TRouteManifest, TRouterSchema>;
     html: HtmlOptions;
     basePath?: string;
     headers?: HeadersInit;
-    headBasePath?: string;
 }
-export interface HandleHeadTagRequestOptions<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape> {
+export interface HandleHeadTagRequestOptions<TRouteManifest extends AnyRoute, TRouterSchema extends AnyRouterSchema> {
     headTags: DefinedHeadTags<TRouteManifest, TRouterSchema>;
     basePath?: string;
-    headBasePath?: string;
 }
 export interface HandleRequestResult {
     matched: boolean;
@@ -74,8 +73,9 @@ export interface DocumentHeadResponsePayload extends RouteHeadResponsePayload {
     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 matchesPassthroughPath(path: string, options: MatchSpaPathOptions): boolean;
+export declare function handleHeadRequest<TRouteManifest extends AnyRoute, TRouterSchema extends AnyRouterSchema>(request: Request, options: HandleHeadTagRequestOptions<TRouteManifest, TRouterSchema>): Promise<HandleRequestResult>;
+export declare function handleHeadTagRequest<TRouteManifest extends AnyRoute, TRouterSchema extends AnyRouterSchema>(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 declare function handleRequest<TRouteManifest extends AnyRoute, TRouterSchema extends AnyRouterSchema>(request: Request, options: HandleRequestOptions<TRouteManifest, TRouterSchema>): Promise<HandleRequestResult>;
 export {};

package/package.json

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