kiru 0.51.0-preview.1 → 0.51.0-preview.2

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/index.ts

@@ -1,3 +1,5 @@
+import { createElement } from "../element.js"
+
 export { useFileRouter, type FileRouterContextType } from "./context.js"
 export * from "./errors.js"
 export { FileRouter, type FileRouterProps } from "./fileRouter.js"
@@ -11,3 +13,9 @@ export const Head = {
   Content,
   Outlet,
 }
+
+export const Body = {
+  Outlet: function BodyOutlet() {
+    return createElement("kiru-body-outlet")
+  },
+}

package/src/router/server/index.ts

@@ -1,4 +1,4 @@
-import { createElement } from "../../element.js"
+import { createElement, Fragment } from "../../element.js"
 import { renderToReadableStream } from "../../ssr/server.js"
 import {
   matchLayouts,
@@ -72,7 +72,7 @@ export async function render(
 
   if (__DEV__) {
     ;[pageEntry, ...layoutEntries].forEach((e) => {
-      ctx.registerModule(e.filePath!)
+      ctx.registerModule(e.absolutePath!)
     })
   }
 
@@ -131,8 +131,21 @@ export async function render(
     props
   )
 
+  let { immediate: documentShell } = renderToReadableStream(
+    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,35 +156,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 { immediate: pageOutletContent, stream } = renderToReadableStream(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,
+    immediate: `<!doctype html>${prePageOutlet}<body>${pageOutletContent}</body>${postPageOutlet}`,
     stream,
   }
 }
@@ -190,7 +206,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 +222,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[]
 }

package/src/router/types.ts

@@ -15,6 +15,7 @@ export interface FileRouterPreloadConfig {
   params: RouteParams
   query: RouteQuery
   route: string
+  cacheData: null | { value: unknown }
 }
 
 export interface FileRouterConfig {
@@ -91,25 +92,54 @@ export interface RouterState {
 
 type PageDataLoaderContext = RouterState & {}
 
+export interface PageDataLoaderCacheConfig {
+  type: "memory" | "localStorage" | "sessionStorage"
+  ttl: number
+}
+
 export type PageDataLoaderConfig<T = unknown> = {
   /**
    * The function to load the page data
    */
   load: (context: PageDataLoaderContext) => 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
+       */
+      mode?: "client"
+      /**
+       * Enable transitions when swapping between "load", "error" and "data" states
+       */
+      transition?: boolean
 
-  /**
-   * 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
-   */
-  mode?: "static" | "client"
-  /**
-   * Enable transitions when swapping between "load", "error" and "data" states (only when mode is "client")
-   */
-  transition?: boolean
-}
+      /**
+       * Configure caching for this loader
+       * @example
+       * ```ts
+       * cache: {
+       *   type: "memory", // or "localStorage" / "sessionStorage"
+       *   ttl: 1000 * 60 * 5, // 5 minutes
+       }
+       * ```
+       */
+      cache?: PageDataLoaderCacheConfig
+    }
+  | {
+      /**
+       * 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
+       */
+      mode: "static"
+    }
+)
 
 export interface PageConfig<T = unknown> {
   /**

package/src/router/utils/index.ts

@@ -65,7 +65,7 @@ function formatViteImportMap(
       load: map[key],
       specificity,
       segments,
-      filePath: key,
+      absolutePath: key,
     }
 
     return {