kiru 0.53.0 → 0.54.0-preview.1

package/src/router/guard.ts

@@ -0,0 +1,72 @@
+import type { NavigationHook } from "./types"
+import type { GuardModule } from "./types.internal"
+
+export type GuardBeforeEach = NavigationHook<
+  void | string | Promise<void | string>
+>
+export type GuardAfterEach = NavigationHook<void | Promise<void>>
+
+export interface NavGuard {
+  beforeEach: GuardBeforeEach
+  afterEach: GuardAfterEach
+}
+
+export const $NAVGUARD_INTERNAL = Symbol.for("kiru:navguard")
+
+export function resolveNavguard(module: GuardModule): NavGuard | null {
+  if (
+    "guard" in module &&
+    $NAVGUARD_INTERNAL in ((module.guard ?? {}) as NavGuardBuilder)
+  ) {
+    return (module.guard as NavGuardBuilder)[$NAVGUARD_INTERNAL]
+  }
+  return null
+}
+
+export interface NavGuardBuilder {
+  beforeEach(...fns: GuardBeforeEach[]): NavGuardBuilder
+  afterEach(...fns: GuardAfterEach[]): NavGuardBuilder
+  get [$NAVGUARD_INTERNAL](): NavGuard
+}
+
+function createNavGuard_impl(
+  beforeEach: GuardBeforeEach[],
+  afterEach: GuardAfterEach[]
+): NavGuard {
+  return {
+    beforeEach: async (ctx, to, from) => {
+      for (const fn of beforeEach) {
+        const res = await fn(ctx, to, from)
+        if (typeof res === "string") {
+          return res
+        }
+      }
+      return
+    },
+    afterEach: async (ctx, to, from) => {
+      for (const fn of afterEach) {
+        await fn(ctx, to, from)
+      }
+    },
+  }
+}
+
+export function createNavGuard(): NavGuardBuilder {
+  const beforeEach: GuardBeforeEach[] = []
+  const afterEach: GuardAfterEach[] = []
+  const guard = createNavGuard_impl(beforeEach, afterEach)
+
+  return {
+    beforeEach(...fns: GuardBeforeEach[]) {
+      beforeEach.push(...fns)
+      return this
+    },
+    afterEach(...fns: GuardAfterEach[]) {
+      afterEach.push(...fns)
+      return this
+    },
+    get [$NAVGUARD_INTERNAL]() {
+      return guard
+    },
+  }
+}

package/src/router/head.ts

@@ -1,5 +1,5 @@
 import { Signal } from "../signals/base.js"
-import { isValidTextChild, isVNode } from "../utils/index.js"
+import { isValidTextChild, isVNode, toArray } from "../utils/index.js"
 import { createElement } from "../element.js"
 import { __DEV__ } from "../env.js"
 import { KiruError } from "../error.js"
@@ -12,7 +12,7 @@ const validHeadChildren = ["title", "base", "link", "meta", "style", "script"]
 function HeadContent({ children }: { children: JSX.Children }): JSX.Element {
   if (__DEV__) {
     const n = node.current!
-    const asArray = Array.isArray(children) ? children : [children]
+    const asArray = toArray(children)
     const invalidNodes = asArray.filter(
       (c) =>
         !isVNode(c) ||
@@ -29,16 +29,14 @@ function HeadContent({ children }: { children: JSX.Children }): JSX.Element {
     }
   }
   if ("window" in globalThis) {
-    const asArray = Array.isArray(children) ? children : [children]
-    const titleNode = asArray.find(
+    const c = toArray(children)
+    const titleNode = c.find(
       (c) => isVNode(c) && c.type === "title"
     ) as Kiru.VNode
 
     if (titleNode) {
       const props = titleNode.props
-      const titleChildren = Array.isArray(props.children)
-        ? props.children
-        : [props.children]
+      const titleChildren = toArray(props.children)
 
       document.title = titleChildren
         .map((c) => (Signal.isSignal(c) ? c.value : c))

package/src/router/index.ts

@@ -1,9 +1,20 @@
 import { createElement } from "../element.js"
 import { __DEV__ } from "../env.js"
 
-export { useFileRouter, type FileRouterContextType } from "./context.js"
+export {
+  useRequestContext,
+  useFileRouter,
+  type FileRouterContextType,
+} from "./context.js"
 export * from "./errors.js"
 export { FileRouter, type FileRouterProps } from "./fileRouter.js"
+export {
+  createNavGuard,
+  type GuardBeforeEach,
+  type GuardAfterEach,
+  type NavGuard,
+  type NavGuardBuilder,
+} from "./guard.js"
 export * from "./link.js"
 export * from "./pageConfig.js"
 export type * from "./types.js"

package/src/router/{server → ssg}/index.ts

@@ -1,25 +1,29 @@
 import { createElement, Fragment } from "../../element.js"
-
 import {
-  matchLayouts,
+  matchModules,
   matchRoute,
   match404Route,
   parseQuery,
   wrapWithLayouts,
 } from "../utils/index.js"
 import { RouterContext } from "../context.js"
-import type { PageConfig, PageProps, RouterState } from "../types.js"
-import { FormattedViteImportMap, PageModule } from "../types.internal.js"
 import { __DEV__ } from "../../env.js"
 import { FileRouterDataLoadError } from "../errors.js"
 import { renderToString } from "../../renderToString.js"
+import type { PageConfig, PageProps, RouterState } from "../types.js"
+import type {
+  FormattedViteImportMap,
+  GuardModule,
+  PageModule,
+} from "../types.internal.js"
 
 export interface RenderContext {
-  pages: FormattedViteImportMap
+  pages: FormattedViteImportMap<PageModule>
   layouts: FormattedViteImportMap
+  guards: FormattedViteImportMap<GuardModule>
   Document: Kiru.FC
   registerModule: (moduleId: string) => void
-  registerPreloadedPageProps: (props: Record<string, unknown>) => void
+  registerStaticProps: (props: Record<string, unknown>) => void
 }
 
 export interface RenderResult {
@@ -64,7 +68,7 @@ export async function render(
 
   const { pageEntry, routeSegments, params } = routeMatch
   const is404Route = routeMatch.routeSegments.includes("404")
-  const layoutEntries = matchLayouts(ctx.layouts, routeSegments)
+  const layoutEntries = matchModules(ctx.layouts, routeSegments)
 
   ;[pageEntry, ...layoutEntries].forEach((e) => {
     ctx.registerModule(e.filePath)
@@ -82,7 +86,7 @@ export async function render(
   const abortController = new AbortController()
 
   if (config.loader) {
-    if (config.loader.mode !== "static" || __DEV__) {
+    if (!config.loader.static || __DEV__) {
       props = { loading: true, data: null, error: null }
     } else {
       const routerState: RouterState = {
@@ -99,7 +103,10 @@ export async function render(
       }, 10000)
 
       try {
-        const data = await config.loader.load(routerState)
+        const data = await config.loader.load({
+          ...routerState,
+          context: {},
+        })
         props = {
           data,
           error: null,
@@ -113,7 +120,7 @@ export async function render(
         }
       } finally {
         clearTimeout(timeout)
-        ctx.registerPreloadedPageProps({ data: props.data, error: props.error })
+        ctx.registerStaticProps({ data: props.data, error: props.error })
       }
     }
   }

package/src/router/ssr/index.ts

@@ -0,0 +1,252 @@
+import path from "path"
+import { createElement, Fragment } from "../../element.js"
+import { __DEV__ } from "../../env.js"
+import { renderToString } from "../../renderToString.js"
+import { renderToReadableStream } from "../../ssr/server.js"
+import { toArray } from "../../utils/format.js"
+import {
+  matchModules,
+  matchRoute,
+  match404Route,
+  parseQuery,
+  wrapWithLayouts,
+  runBeforeEachGuards,
+  runAfterEachGuards,
+  runBeforeEnterHooks,
+} from "../utils/index.js"
+import { RouterContext, RequestContext } from "../context.js"
+import type { PageConfig, PageProps, RouterState } from "../types.js"
+import type {
+  FormattedViteImportMap,
+  GuardModule,
+  PageModule,
+} from "../types.internal.js"
+import { createStatefulPromise } from "../../utils/promise.js"
+import { PAGE_DATA_PROMISE_ID } from "../constants.js"
+
+export interface SSRRenderContext {
+  pages: FormattedViteImportMap<PageModule>
+  layouts: FormattedViteImportMap
+  guards: FormattedViteImportMap<GuardModule>
+  Document: Kiru.FC
+  userContext: Kiru.RequestContext
+  registerModule: (moduleId: string) => void
+}
+
+export interface SSRHttpResponse {
+  html: string
+  statusCode: number
+  headers: Array<[string, string]>
+  stream: ReadableStream | null
+}
+
+export interface SSRRenderResult {
+  httpResponse: SSRHttpResponse | null
+}
+
+export async function render(
+  url: string,
+  ctx: SSRRenderContext
+): Promise<SSRRenderResult> {
+  const extName = path.extname(url)
+  if (extName && extName.length > 0) {
+    return { httpResponse: null }
+  } else if (url.startsWith("/@")) {
+    return { httpResponse: null }
+  }
+
+  const u = new URL(url, "http://localhost")
+  const pathSegments = u.pathname.split("/").filter(Boolean)
+  let routeMatch = matchRoute(ctx.pages, pathSegments)
+
+  if (!routeMatch) {
+    // Try to find a 404 page in parent directories
+    const fourOhFourMatch = match404Route(ctx.pages, pathSegments)
+    if (fourOhFourMatch) {
+      routeMatch = fourOhFourMatch
+    } else {
+      // Fallback to root 404 or default fallback
+      if (url === "/404") {
+        if (__DEV__) {
+          console.warn(
+            "[kiru/router]: No 404 route defined. Using fallback 404 page."
+          )
+        }
+        return {
+          httpResponse: {
+            statusCode: 404,
+            headers: [["Content-Type", "text/html"]],
+            html: "<!doctype html><html><head><title>Not Found</title></head><body><h1>404</h1></body></html>",
+            stream: null,
+          },
+        }
+      }
+      // Recursively render the 404 page
+      const notFoundResponse = await render("/404", ctx)
+      return {
+        httpResponse: {
+          html: notFoundResponse.httpResponse?.html ?? "",
+          headers: notFoundResponse.httpResponse?.headers ?? [
+            ["Content-Type", "text/html"],
+          ],
+          ...notFoundResponse,
+          statusCode: 404,
+          stream: null,
+        },
+      }
+    }
+  }
+  const { pageEntry, routeSegments, params } = routeMatch
+  const is404Route = routeMatch.routeSegments.includes("404")
+
+  const guardEntries = matchModules(ctx.guards, routeSegments)
+  const guardModules = await Promise.all(
+    guardEntries.map((entry) => entry.load() as unknown as Promise<GuardModule>)
+  )
+
+  const redirectPath = await runBeforeEachGuards(
+    guardModules,
+    { ...ctx.userContext },
+    u.pathname
+  )
+
+  if (redirectPath !== null) {
+    return createRedirectResult(redirectPath)
+  }
+
+  const layoutEntries = matchModules(ctx.layouts, routeSegments)
+
+  // Register all modules for CSS collection
+  ;[pageEntry, ...layoutEntries].forEach((e) => {
+    ctx.registerModule(e.filePath)
+  })
+
+  const [page, ...layouts] = await Promise.all([
+    pageEntry.load(),
+    ...layoutEntries.map((layoutEntry) => layoutEntry.load()),
+  ])
+
+  const onBeforeEnter = page.config?.hooks?.onBeforeEnter
+  if (onBeforeEnter) {
+    const redirectPath = await runBeforeEnterHooks(
+      toArray(onBeforeEnter),
+      { ...ctx.userContext },
+      u.pathname
+    )
+    if (redirectPath !== null) {
+      return createRedirectResult(redirectPath)
+    }
+  }
+
+  let documentShell = renderToString(createElement(ctx.Document))
+
+  if (
+    documentShell.includes("</body>") ||
+    !documentShell.includes("<kiru-body-outlet>")
+  ) {
+    throw new Error(
+      "[kiru/router]: Document is expected to contain a <Body.Outlet> element. See https://kirujs.dev/docs/api/file-router#general-usage"
+    )
+  }
+
+  const query = parseQuery(u.search)
+
+  let props = {} as PageProps<PageConfig>
+  const config = page.config ?? {}
+  const abortSignal = new AbortController().signal
+
+  const routerState: RouterState = {
+    params,
+    query,
+    pathname: u.pathname,
+    hash: "",
+    signal: abortSignal,
+  }
+
+  let pageDataPromise: Kiru.StatefulPromise<unknown> | null = null
+  if (config.loader && !config.loader.static) {
+    props = {
+      data: null,
+      error: null,
+      loading: true,
+    }
+    const promise = config.loader.load({
+      ...routerState,
+      context: { ...ctx.userContext },
+    })
+    pageDataPromise = createStatefulPromise(PAGE_DATA_PROMISE_ID, promise)
+  }
+
+  const children = wrapWithLayouts(
+    layouts
+      .map((layout) => layout.default)
+      .filter((l) => typeof l === "function"),
+    page.default,
+    props
+  )
+
+  const app = createElement(RouterContext.Provider, {
+    children: createElement(RequestContext.Provider, {
+      children: Fragment({ children }),
+      value: ctx.userContext,
+    }),
+    value: { state: routerState },
+  })
+
+  let { immediate: pageOutletContent, stream } = renderToReadableStream(app, {
+    data: pageDataPromise ? [pageDataPromise] : [],
+  })
+
+  const hasHeadContent = pageOutletContent.includes("<kiru-head-content>")
+  const hasHeadOutlet = documentShell.includes("<kiru-head-outlet>")
+
+  if (hasHeadOutlet && hasHeadContent) {
+    let [preHeadContent = "", headContentInner = "", postHeadContent = ""] =
+      pageOutletContent.split(/<kiru-head-content>|<\/kiru-head-content>/)
+
+    documentShell = documentShell.replace(
+      "<kiru-head-outlet>",
+      headContentInner
+    )
+    pageOutletContent = `${preHeadContent}${postHeadContent}`
+  } else if (hasHeadContent) {
+    // remove head content element and everything within it
+    pageOutletContent = pageOutletContent.replace(
+      /<kiru-head-content>(.*?)<\/kiru-head-content>/,
+      ""
+    )
+  } else if (hasHeadOutlet) {
+    // remove head outlet element and everything within it
+    documentShell = documentShell.replaceAll("<kiru-head-outlet>", "")
+  }
+
+  const [prePageOutlet, postPageOutlet] =
+    documentShell.split("<kiru-body-outlet>")
+
+  const html = `<!DOCTYPE html>${prePageOutlet}<body>${pageOutletContent}</body>${postPageOutlet}`
+  const statusCode = is404Route ? 404 : 200
+
+  queueMicrotask(() => {
+    runAfterEachGuards(guardModules, { ...ctx.userContext }, u.pathname)
+  })
+
+  return {
+    httpResponse: {
+      html,
+      statusCode,
+      headers: [["Content-Type", "text/html;charset=utf-8"]],
+      stream,
+    },
+  }
+}
+
+function createRedirectResult(to: string): SSRRenderResult {
+  return {
+    httpResponse: {
+      statusCode: 302,
+      headers: [["Location", to]],
+      html: "",
+      stream: null,
+    },
+  }
+}

package/src/router/types.internal.ts

@@ -1,5 +1,6 @@
 import type { FileRouterContextType } from "./context"
 import type { PageConfig } from "./types"
+import type { NavGuardBuilder } from "./guard"
 
 export interface CurrentPage {
   component: Kiru.FC<any>
@@ -20,6 +21,10 @@ export interface PageModule {
   >
 }
 
+export interface GuardModule {
+  guard: NavGuardBuilder
+}
+
 export interface ViteImportMap {
   [fp: string]: () => Promise<DefaultComponentModule>
 }

package/src/router/types.ts

@@ -3,14 +3,17 @@ import type { FileRouterDataLoadError } from "./errors"
 import type {
   DefaultComponentModule,
   FormattedViteImportMap,
+  GuardModule,
   PageModule,
 } from "./types.internal"
 
 export interface FileRouterPreloadConfig {
-  pages: FormattedViteImportMap
+  pages: FormattedViteImportMap<PageModule>
   layouts: FormattedViteImportMap
+  guards?: FormattedViteImportMap<GuardModule>
   page: PageModule
   pageProps: Record<string, unknown>
+  pagePropsPromise?: Promise<AsyncTaskState<unknown, FileRouterDataLoadError>>
   pageLayouts: DefaultComponentModule[]
   params: RouteParams
   query: RouteQuery
@@ -40,6 +43,14 @@ export interface FileRouterConfig {
    * ```
    */
   layouts: Record<string, unknown>
+  /**
+   * The import map to use for loading nav guards
+   * @example
+   * ```tsx
+   * <FileRouter config={{ guards: import.meta.glob("/∗∗/guard.{ts,js}"), ... }} />
+   * ```
+   */
+  guards?: Record<string, unknown>
 
   /**
    * The base url to use as a prefix for route matching
@@ -98,28 +109,40 @@ export interface RouterState {
   signal: AbortSignal
 }
 
-type PageDataLoaderContext = RouterState & {}
-
 export interface PageDataLoaderCacheConfig {
   type: "memory" | "localStorage" | "sessionStorage"
   ttl: number
 }
 
+interface LoaderContext extends RouterState {
+  /**
+   * The request context - in SSR, this is the data from the server
+   * that's passed to the `renderPage` function
+   * @example
+   * ```ts
+   * // server.ts
+   * renderPage({ url, context: { test: 123 } })
+   *
+   * // page.tsx
+   * loader: {
+   *   load: ({ context }) => context.test
+   * }
+   * ```
+   */
+  context: Kiru.RequestContext
+}
+
 export type PageDataLoaderConfig<T = unknown> = {
   /**
    * The function to load the page data
    */
-  load: (context: PageDataLoaderContext) => Promise<T>
+  load: (context: LoaderContext) => Promise<T>
 } & (
   | {
       /**
-       * The mode to use for the page data loader
-       * @default "client"
-       * @description
-       * - **static**: The page data is loaded at build time and never updated
-       * - **client**: The page data is loaded upon navigation and updated on subsequent navigations
+       * Indicates that the page data should only be loaded at build time
        */
-      mode?: "client"
+      static?: false
       /**
        * Enable transitions when swapping between "load", "error" and "data" states
        */
@@ -139,16 +162,28 @@ export type PageDataLoaderConfig<T = unknown> = {
     }
   | {
       /**
-       * The mode to use for the page data loader
-       * @default "client"
-       * @description
-       * - **static**: The page data is loaded at build time and never updated
-       * - **client**: The page data is loaded upon navigation and updated on subsequent navigations
+       * Indicates that the page data should only be loaded at build time
        */
-      mode: "static"
+      static: true
     }
 )
 
+export type NavigationHook<T> = (
+  context: Kiru.RequestContext,
+  to: string,
+  from: string
+) => T
+
+export type OnBeforeEnterHook = NavigationHook<
+  string | void | Promise<string | void>
+>
+export type OnBeforeLeaveHook = NavigationHook<false | void>
+
+interface PageContextHooks {
+  onBeforeEnter?: OnBeforeEnterHook | OnBeforeEnterHook[]
+  onBeforeLeave?: OnBeforeLeaveHook | OnBeforeLeaveHook[]
+}
+
 export interface PageConfig<T = unknown> {
   /**
    * The loader configuration for this page
@@ -159,6 +194,8 @@ export interface PageConfig<T = unknown> {
    * returned, a page will be generated
    */
   generateStaticParams?: () => RouteParams[] | Promise<RouteParams[]>
+
+  hooks?: PageContextHooks
 }
 
 export type PageProps<T extends PageConfig<any>> = T extends PageConfig<infer U>