kiru 0.51.0-preview.1 → 0.51.0

package/src/router/fileRouterController.ts

@@ -1,9 +1,9 @@
 import { Signal } from "../signals/base.js"
-import { flushSync } from "../scheduler.js"
+import { flushSync, nextIdle } from "../scheduler.js"
 import { __DEV__ } from "../env.js"
 import { type FileRouterContextType } from "./context.js"
 import { FileRouterDataLoadError } from "./errors.js"
-import { fileRouterInstance, fileRouterRoute } from "./globals.js"
+import { fileRouterInstance, fileRouterRoute, routerCache } from "./globals.js"
 import type {
   FileRouterConfig,
   PageConfig,
@@ -26,6 +26,7 @@ import {
   parseQuery,
   wrapWithLayouts,
 } from "./utils/index.js"
+import { RouterCache, type CacheKey } from "./cache.js"
 
 interface PageConfigWithLoader<T = unknown> extends PageConfig {
   loader: PageDataLoaderConfig<T>
@@ -34,7 +35,7 @@ interface PageConfigWithLoader<T = unknown> extends PageConfig {
 export class FileRouterController {
   public contextValue: FileRouterContextType
   private enableTransitions: boolean
-  private pages: FormattedViteImportMap
+  private pages: FormattedViteImportMap<PageModule>
   private layouts: FormattedViteImportMap
   private abortController: AbortController
   private currentPage: Signal<{
@@ -53,6 +54,7 @@ export class FileRouterController {
   private pageRouteToConfig?: Map<string, PageConfig>
 
   constructor() {
+    routerCache.current ??= new RouterCache()
     this.enableTransitions = false
     this.pages = {}
     this.layouts = {}
@@ -68,6 +70,7 @@ export class FileRouterController {
     }
     const __this = this
     this.contextValue = {
+      invalidate: this.invalidate.bind(this),
       get state() {
         return __this.state
       },
@@ -114,11 +117,12 @@ export class FileRouterController {
         route,
         params,
         query,
+        cacheData,
       } = preloaded
       this.state = {
         params,
         query,
-        path: route,
+        path: window.location.pathname,
         signal: this.abortController.signal,
       }
       this.currentPage.value = {
@@ -139,20 +143,30 @@ export class FileRouterController {
         validateRoutes(this.pages)
       }
       const loader = page.config?.loader
-      if (__DEV__) {
-        if (loader) {
+      if (loader && loader.mode !== "static" && pageProps.loading === true) {
+        if (cacheData === null) {
           this.loadRouteData(
             page.config as PageConfigWithLoader,
             pageProps,
             this.state
           )
+        } else {
+          nextIdle(() => {
+            const props = {
+              ...pageProps,
+              data: cacheData.value,
+              error: null,
+              loading: false,
+            }
+            let transition = this.enableTransitions
+            if (loader.transition !== undefined) {
+              transition = loader.transition
+            }
+            handleStateTransition(this.state.signal, transition, () => {
+              this.currentPageProps.value = props
+            })
+          })
         }
-      } else if (loader && loader.mode !== "static") {
-        this.loadRouteData(
-          page.config as PageConfigWithLoader,
-          pageProps,
-          this.state
-        )
       }
     } else {
       this.pages = formatViteImportMap(
@@ -182,28 +196,55 @@ export class FileRouterController {
       return
     }
     const curPage = this.currentPage.value
-    if (curPage?.route === existing.route && config.loader) {
+    const loader = config.loader
+    if (curPage?.route === existing.route && loader) {
       const p = this.currentPageProps.value
       let transition = this.enableTransitions
-      if (config.loader.transition !== undefined) {
-        transition = config.loader.transition
+      if (loader.mode !== "static" && loader.transition !== undefined) {
+        transition = loader.transition
       }
-      const props = {
-        ...p,
-        loading: true,
-        data: null,
-        error: null,
+
+      // Check cache first if caching is enabled
+      let cachedData = null
+      if (loader.mode !== "static" && loader.cache) {
+        const cacheKey: CacheKey = {
+          path: this.state.path,
+          params: this.state.params,
+          query: this.state.query,
+        }
+        cachedData = routerCache.current!.get(cacheKey, loader.cache)
       }
-      handleStateTransition(this.state.signal, transition, () => {
-        this.currentPageProps.value = props
-      })
 
-      this.loadRouteData(
-        config as PageConfigWithLoader,
-        props,
-        this.state,
-        transition
-      )
+      if (cachedData !== null) {
+        // Use cached data immediately - no loading state needed
+        const props = {
+          ...p,
+          data: cachedData.value,
+          error: null,
+          loading: false,
+        }
+        handleStateTransition(this.state.signal, transition, () => {
+          this.currentPageProps.value = props
+        })
+      } else {
+        // No cached data - show loading state and load data
+        const props = {
+          ...p,
+          loading: true,
+          data: null,
+          error: null,
+        }
+        handleStateTransition(this.state.signal, transition, () => {
+          this.currentPageProps.value = props
+        })
+
+        this.loadRouteData(
+          config as PageConfigWithLoader,
+          props,
+          this.state,
+          transition
+        )
+      }
     }
 
     this.pageRouteToConfig?.set(existing.route, config)
@@ -269,7 +310,7 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
       )
 
       const [page, ...layouts] = await Promise.all([
-        pagePromise as Promise<PageModule>,
+        pagePromise,
         ...layoutPromises,
       ])
 
@@ -301,19 +342,41 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
 
       if (loader) {
         if (loader.mode !== "static" || __DEV__) {
-          props = {
-            ...props,
-            loading: true,
-            data: null,
-            error: null,
-          } satisfies PageProps<PageConfig<unknown>>
+          // Check cache first if caching is enabled
+          let cachedData = null
+          if (loader.mode !== "static" && loader.cache) {
+            const cacheKey: CacheKey = {
+              path: routerState.path,
+              params: routerState.params,
+              query: routerState.query,
+            }
+            cachedData = routerCache.current!.get(cacheKey, loader.cache)
+          }
 
-          this.loadRouteData(
-            config as PageConfigWithLoader,
-            props,
-            routerState,
-            enableTransition
-          )
+          if (cachedData !== null) {
+            // Use cached data immediately - no loading state needed
+            props = {
+              ...props,
+              data: cachedData.value,
+              error: null,
+              loading: false,
+            } satisfies PageProps<PageConfig<unknown>>
+          } else {
+            // No cached data - show loading state and load data
+            props = {
+              ...props,
+              loading: true,
+              data: null,
+              error: null,
+            } satisfies PageProps<PageConfig<unknown>>
+
+            this.loadRouteData(
+              config as PageConfigWithLoader,
+              props,
+              routerState,
+              enableTransition
+            )
+          }
         } else {
           const staticProps = page.__KIRU_STATIC_PROPS__?.[path]
           if (!staticProps) {
@@ -355,15 +418,28 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
     enableTransition = this.enableTransitions
   ) {
     const { loader } = config
+
+    // Load data from loader (cache check is now done earlier in loadRoute)
     loader
       .load(routerState)
       .then(
-        (data) =>
-          ({
+        (data) => {
+          // Cache the data if caching is enabled
+          if (loader.mode !== "static" && loader.cache) {
+            const cacheKey: CacheKey = {
+              path: routerState.path,
+              params: routerState.params,
+              query: routerState.query,
+            }
+            routerCache.current!.set(cacheKey, data, loader.cache)
+          }
+
+          return {
             data,
             error: null,
             loading: false,
-          } satisfies PageProps<PageConfig<unknown>>),
+          } satisfies PageProps<PageConfig<unknown>>
+        },
         (error) =>
           ({
             data: null,
@@ -375,7 +451,7 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
         if (routerState.signal.aborted) return
 
         let transition = enableTransition
-        if (loader.transition !== undefined) {
+        if (loader.mode !== "static" && loader.transition !== undefined) {
           transition = loader.transition
         }
 
@@ -388,6 +464,23 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
       })
   }
 
+  private invalidate(...paths: string[]) {
+    // Invalidate cache entries
+    routerCache.current!.invalidate(...paths)
+
+    // Check if current page matches any invalidated paths
+    const currentPath = this.state.path
+    const shouldRefresh = routerCache.current!.pathMatchesPattern(
+      currentPath,
+      paths
+    )
+
+    if (shouldRefresh) {
+      // Refresh the current page to get fresh data
+      this.loadRoute(currentPath, {}, this.enableTransitions)
+    }
+  }
+
   private async navigate(
     path: string,
     options?: {
@@ -482,7 +575,7 @@ function validateRoutes(pageMap: FormattedViteImportMap) {
     let warning = "[kiru/router]: Route conflicts detected:\n"
     warning += routeConflicts
       .map(([route1, route2]) => {
-        return `  - "${route1.filePath}" conflicts with "${route2.filePath}"\n`
+        return `  - "${route1.absolutePath}" conflicts with "${route2.absolutePath}"\n`
       })
       .join("")
     warning += "Routes are ordered by specificity (higher specificity wins)"

package/src/router/globals.ts

@@ -1,3 +1,4 @@
+import type { RouterCache } from "./cache"
 import type { FileRouterController } from "./fileRouterController"
 
 export const fileRouterInstance = {
@@ -7,3 +8,7 @@ export const fileRouterInstance = {
 export const fileRouterRoute = {
   current: null as string | null,
 }
+
+export const routerCache = {
+  current: null as RouterCache | null,
+}

package/src/router/head.ts

@@ -1,66 +1,56 @@
-import { createElement } from "../index.js"
 import { Signal } from "../signals/base.js"
 import { isValidTextChild, isVNode } from "../utils/index.js"
+import { createElement } from "../element.js"
+import { __DEV__ } from "../env.js"
+import { KiruError } from "../error.js"
+import { node } from "../globals.js"
 
-export { Content, Outlet }
+export { HeadContent, HeadOutlet }
 
-/**
- * Used with SSG. Renders content to the document head via a corresponding `<Head.Outlet>` component placed in your `document.tsx`.
- * @example
- * // src/pages/index.tsx
- * export default function Index() {
- *   return (
- *     <div>
- *       <Head.Content>
- *         <title>My App - Home</title>
- *       </Head.Content>
- *       <h1>Home</h1>
- *     </div>
- *   )
- }
- */
-function Content({ children }: { children: JSX.Children }) {
-  if ("window" in globalThis) {
-    ;(Array.isArray(children) ? children : [children])
-      .filter(isVNode)
-      .forEach(({ type, props }) => {
-        switch (type) {
-          case "title":
-            const title = (
-              Array.isArray(props.children) ? props.children : [props.children]
-            )
-              .map((c) => (Signal.isSignal(c) ? c.value : c))
-              .filter(isValidTextChild)
-              .join("")
-            return (document.title = title)
-          case "meta":
-            return document
-              .querySelector(`meta[name="${props.name}"]`)
-              ?.setAttribute("content", String(props.content))
-        }
+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 invalidNodes = asArray.filter(
+      (c) =>
+        !isVNode(c) ||
+        typeof c.type !== "string" ||
+        !validHeadChildren.includes(c.type)
+    )
+    if (invalidNodes.length) {
+      throw new KiruError({
+        message: `[kiru/router]: <Head.Content> only accepts title, base, link, meta, style and script elements as children. Received: ${invalidNodes.map(
+          (n) => (isVNode(n) ? `<${n.type.toString()}>` : `"${n}"`)
+        )}`,
+        vNode: n,
       })
+    }
+  }
+  if ("window" in globalThis) {
+    const asArray = Array.isArray(children) ? children : [children]
+    const titleNode = asArray.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]
+
+      document.title = titleChildren
+        .map((c) => (Signal.isSignal(c) ? c.value : c))
+        .filter(isValidTextChild)
+        .join("")
+    }
+
     return null
   }
   return createElement("kiru-head-content", { children })
 }
 
-/**
- * Used with SSG. Renders content to the document head from a `<Head>` component in the currently rendered page.
- * @example
- * // document.tsx
- * export default function Document() {
- *   return (
- *     <html lang="en">
- *       <head>
- *         <meta charset="utf-8" />
- *         <meta name="viewport" content="width=device-width, initial-scale=1" />
- *         <Head.Outlet />
- *       </head>
- *       <body>{children}</body>
- *     </html>
- *   )
- }
- */
-function Outlet() {
+function HeadOutlet(): JSX.Element {
   return createElement("kiru-head-outlet")
 }

package/src/router/index.ts

@@ -1,3 +1,6 @@
+import { createElement } from "../element.js"
+import { __DEV__ } from "../env.js"
+
 export { useFileRouter, type FileRouterContextType } from "./context.js"
 export * from "./errors.js"
 export { FileRouter, type FileRouterProps } from "./fileRouter.js"
@@ -5,9 +8,73 @@ export * from "./link.js"
 export * from "./pageConfig.js"
 export type * from "./types.js"
 
-import { Content, Outlet } from "./head.js"
+import { HeadContent, HeadOutlet } from "./head.js"
 
 export const Head = {
-  Content,
-  Outlet,
+  /**
+ * - During SSG, renders content to the document head via a corresponding `<Head.Outlet>` component placed in your `document.tsx`.
+ * - During CSR, updates document title.
+ * @example
+ * // src/pages/index.tsx
+ * export default function Index() {
+ *   return (
+ *     <div>
+ *       <Head.Content>
+ *         <title>My App - Home</title>
+ *       </Head.Content>
+ *       <h1>Home</h1>
+ *     </div>
+ *   )
+ }
+ */
+  Content: HeadContent,
+  /**
+ * Used with SSG. Renders content to the document head from a `<Head>` component in the currently rendered page.
+ * @example
+ * // src/pages/document.tsx
+ * export default function Document() {
+ *   return (
+ *     <html lang="en">
+ *       <head>
+ *         <meta charset="utf-8" />
+ *         <meta name="viewport" content="width=device-width, initial-scale=1" />
+ *         <Head.Outlet />
+ *       </head>
+ *       <Body.Outlet />
+ *     </html>
+ *   )
+ }
+ */
+  Outlet: HeadOutlet,
+}
+
+export const Body = {
+  /**
+   * Used with SSG 'document' files. Renders content to the document body via a corresponding `<Body.Outlet>` component placed in your `document.tsx`.
+   * @example
+   * // src/pages/document.tsx
+   * export default function Document() {
+   *   return (
+   *     <html lang="en">
+   *       <head>
+   *         <meta charset="utf-8" />
+   *         <meta name="viewport" content="width=device-width, initial-scale=1" />
+   *         <Head.Outlet />
+   *       </head>
+   *       <Body.Outlet />
+   *     </html>
+   *   )
+   }
+   */
+  Outlet: BodyOutlet,
+}
+
+function BodyOutlet() {
+  return createElement("kiru-body-outlet")
+}
+
+if (__DEV__) {
+  ;(Head.Content as Kiru.FC).displayName = "Kiru.Head.Content"
+  ;(Head.Outlet as Kiru.FC).displayName = "Kiru.Head.Outlet"
+  ;(Body.Outlet as Kiru.FC).displayName = "Kiru.Body.Outlet"
 }

package/src/router/server/index.ts

@@ -1,5 +1,5 @@
-import { createElement } from "../../element.js"
-import { renderToReadableStream } from "../../ssr/server.js"
+import { createElement, Fragment } from "../../element.js"
+
 import {
   matchLayouts,
   matchRoute,
@@ -9,10 +9,10 @@ import {
 } from "../utils/index.js"
 import { RouterContext } from "../context.js"
 import type { PageConfig, PageProps, RouterState } from "../types.js"
-import type { Readable } from "node:stream"
 import { FormattedViteImportMap, PageModule } from "../types.internal.js"
 import { __DEV__ } from "../../env.js"
 import { FileRouterDataLoadError } from "../errors.js"
+import { renderToString } from "../../renderToString.js"
 
 export interface RenderContext {
   pages: FormattedViteImportMap
@@ -24,8 +24,7 @@ export interface RenderContext {
 
 export interface RenderResult {
   status: number
-  immediate: string
-  stream: Readable | null
+  body: string
 }
 
 export async function render(
@@ -52,15 +51,12 @@ export async function render(
         }
         return {
           status: 404,
-          immediate:
-            "<!doctype html><html><head><title>Not Found</title></head><body><h1>404</h1></body></html>",
-          stream: null,
+          body: "<!doctype html><html><head><title>Not Found</title></head><body><h1>404</h1></body></html>",
         }
       }
       return render("/404", ctx, {
         ...(result ?? {}),
-        immediate: "",
-        stream: null,
+        body: "",
         status: 404,
       })
     }
@@ -72,7 +68,7 @@ export async function render(
 
   if (__DEV__) {
     ;[pageEntry, ...layoutEntries].forEach((e) => {
-      ctx.registerModule(e.filePath!)
+      ctx.registerModule(e.absolutePath!)
     })
   }
 
@@ -131,8 +127,19 @@ export async function render(
     props
   )
 
+  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#ssg"
+    )
+  }
+
   const app = createElement(RouterContext.Provider, {
-    children: createElement(ctx.Document, { children }),
+    children: Fragment({ children }),
     value: {
       state: {
         params,
@@ -143,36 +150,38 @@ export async function render(
     },
   })
 
-  let { immediate, stream } = renderToReadableStream(app)
-  const hasHeadOutlet = immediate.includes("<kiru-head-outlet>")
-  const hasHeadContent = immediate.includes("<kiru-head-content>")
+  let pageOutletContent = renderToString(app)
+  const hasHeadContent = pageOutletContent.includes("<kiru-head-content>")
+  const hasHeadOutlet = documentShell.includes("<kiru-head-outlet>")
 
   if (hasHeadOutlet && hasHeadContent) {
     let [preHeadContent = "", headContentInner = "", postHeadContent = ""] =
-      immediate.split(/<kiru-head-content>|<\/kiru-head-content>/)
+      pageOutletContent.split(/<kiru-head-content>|<\/kiru-head-content>/)
 
-    preHeadContent = preHeadContent.replace(
+    documentShell = documentShell.replace(
       "<kiru-head-outlet>",
       headContentInner
     )
-    immediate = `${preHeadContent}${postHeadContent}`
+    pageOutletContent = `${preHeadContent}${postHeadContent}`
   } else if (hasHeadContent) {
     // remove head content element and everything within it
-    immediate = immediate.replace(
+    pageOutletContent = pageOutletContent.replace(
       /<kiru-head-content>(.*?)<\/kiru-head-content>/,
       ""
     )
   } else if (hasHeadOutlet) {
     // remove head outlet element and everything within it
-    immediate = immediate.replaceAll("<kiru-head-outlet>", "")
+    documentShell = documentShell.replaceAll("<kiru-head-outlet>", "")
   }
 
+  const [prePageOutlet, postPageOutlet] =
+    documentShell.split("<kiru-body-outlet>")
+
   // console.log("immediate", immediate)
 
   return {
     status: is404Route ? 404 : result?.status ?? 200,
-    immediate: "<!doctype html>" + immediate,
-    stream,
+    body: `<!doctype html>${prePageOutlet}<body>${pageOutletContent}</body>${postPageOutlet}`,
   }
 }
 
@@ -190,7 +199,7 @@ export async function generateStaticPaths(pages: FormattedViteImportMap) {
 
     const hasDynamic = urlSegments.some((s) => s.startsWith(":"))
     if (!hasDynamic) {
-      results[basePath === "" ? "/" : basePath] = entry.filePath
+      results[basePath === "" ? "/" : basePath] = entry.absolutePath
       continue
     }
     try {
@@ -206,7 +215,7 @@ export async function generateStaticPaths(pages: FormattedViteImportMap) {
           const value = params[key]
           p = p.replace(`:${key}*`, value).replace(`:${key}`, value)
         }
-        results[p] = entry.filePath
+        results[p] = entry.absolutePath
       }
     } catch {}
   }

package/src/router/types.internal.ts

@@ -17,18 +17,20 @@ export interface ViteImportMap {
   [fp: string]: () => Promise<DefaultComponentModule>
 }
 
-export interface FormattedViteImportMap {
-  [key: string]: {
-    load: () => Promise<DefaultComponentModule>
-    specificity: number
-    segments: string[]
-    filePath: string
-  }
+export interface FormattedViteImportMapEntry<T = DefaultComponentModule> {
+  load: () => Promise<T>
+  specificity: number
+  segments: string[]
+  absolutePath: string
+}
+
+export interface FormattedViteImportMap<T = DefaultComponentModule> {
+  [key: string]: FormattedViteImportMapEntry<T>
 }
 
 export interface RouteMatch {
   route: string
-  pageEntry: FormattedViteImportMap[string]
+  pageEntry: FormattedViteImportMapEntry<PageModule>
   params: Record<string, string>
   routeSegments: string[]
 }