@blueprint-ts/core 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## v2.0.0 - 2026-02-18
+
+# [2.0.0](/compare/v1.2.0...v2.0.0) (2026-02-18)
+
+
+### Features
+
+* Cache resolved route resources for child routes db70b77
 ## v1.2.0 - 2026-01-25
 
 # [1.2.0](/compare/v1.1.2...v1.2.0) (2026-01-25)

package/docs/vue/requests/route-resource-binding.md

@@ -1,4 +1,4 @@
-# Route Model Binding
+# Route Resource Binding
 
 When using `vue-router`, you can automatically bind route parameters to resources, similar to how Laravel's route model binding works.
 
@@ -7,60 +7,228 @@ When using `vue-router`, you can automatically bind route parameters to resource
 To enable the router to load resources automatically, install the route injection plugin when initializing your router:
 
 ```ts
+import { installRouteInjection } from '@blueprint-ts/core'
+
 installRouteInjection(router)
 ```
 
-### Defining Routes
+## Defining Routes
 
 Use the `defineRoute` helper to define your routes and specify which parameters should be resolved into resources:
 
 ```ts
-defineRoute<{
+import { defineRoute, RouteResourceRequestResolver } from '@blueprint-ts/core'
+import ProductDetailPage from '@/pages/ProductDetailPage.vue'
+
+export default defineRoute<{
     product: ProductResource
 }>()({
     path: ':productId',
     name: 'products.show',
     component: ProductDetailPage,
-    meta: {
-        inject: {
-            product: {
-                from: 'productId',
-                resolve: (productId: string) => {
-                    return new RouteModelRequestResolver(
-                        new ProductShowRequest(productId)
-                    )
-                }
+    inject: {
+        product: {
+            from: 'productId',
+            resolve: (productId: string) => {
+                return new RouteResourceRequestResolver(
+                    new ProductShowRequest(productId)
+                )
             }
         }
     }
 })
 ```
 
-The `beforeResolve` navigation guard will automatically fetch the `ProductResource` using the `ProductShowRequest` and the `productId` from the route.
+Navigation is **non-blocking** — the route navigates immediately while resources resolve in the background. Cached values are reused when navigating between child routes with unchanged parameters.
 
 ## Usage in Components
 
-Your component can then directly access the resolved resource via props:
+Your component can directly access the resolved resource via props:
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{
+    product: ProductResource
+}>()
+</script>
+```
+
+## Handling Loading & Error States
+
+### Using `RouteResourceBoundView`
+
+`RouteResourceBoundView` is a drop-in replacement for `<RouterView>` that automatically handles loading and error states. Define error and loading components directly in the route:
+
+```ts
+import { defineRoute, RouteResourceRequestResolver } from '@blueprint-ts/core'
+import ProductDetailPage from '@/pages/ProductDetailPage.vue'
+import GenericErrorPage from '@/pages/GenericErrorPage.vue'
+import LoadingSpinner from '@/components/LoadingSpinner.vue'
+
+export default defineRoute<{
+    product: ProductResource
+}>()({
+    path: ':productId',
+    name: 'products.show',
+    component: ProductDetailPage,
+    errorComponent: GenericErrorPage,
+    loadingComponent: LoadingSpinner,
+    inject: {
+        product: {
+            from: 'productId',
+            resolve: (productId: string) => {
+                return new RouteResourceRequestResolver(
+                    new ProductShowRequest(productId)
+                )
+            }
+        }
+    }
+})
+```
+
+Then replace `<RouterView>` with `<RouteResourceBoundView>` in your layout:
+
+```vue
+<template>
+  <RouteResourceBoundView />
+</template>
+
+<script setup lang="ts">
+import { RouteResourceBoundView } from '@blueprint-ts/core'
+</script>
+```
+
+The `errorComponent` receives `error` and `refresh` as props. The `refresh` function retries all failed resources:
+
+```vue
+<!-- GenericErrorPage.vue -->
+<template>
+  <div>
+    <p>{{ error.message }}</p>
+    <button @click="refresh">Try Again</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+    error: Error
+    refresh: () => Promise<void>
+}>()
+</script>
+```
+
+#### Using Scoped Slots
+
+`RouteResourceBoundView` supports the same `v-slot` pattern as `<RouterView>`:
+
+```vue
+<RouteResourceBoundView v-slot="{ Component, route }">
+  <component
+    :is="Component"
+    v-if="Component"
+  />
+  <EmptyState v-else />
+</RouteResourceBoundView>
+```
+
+When no `errorComponent` or `loadingComponent` is defined on the route, you can use named slots as fallbacks:
 
 ```vue
+<RouteResourceBoundView>
+  <template #default="{ Component, route }">
+    <component :is="Component" v-if="Component" />
+  </template>
+
+  <template #loading>
+    <LoadingSpinner />
+  </template>
+
+  <template #error="{ error, refresh }">
+    <div>
+      <p>{{ error.message }}</p>
+      <button @click="refresh">Retry</button>
+    </div>
+  </template>
+</RouteResourceBoundView>
+```
+
+### Using `useRouteResource` (Manual Handling)
+
+If you prefer to handle loading and error states inside the component itself, set `lazy: false` on the route. This renders the component immediately while resources resolve in the background:
+
+```ts
+export default defineRoute<{
+    product: ProductResource
+}>()({
+    path: ':productId',
+    name: 'products.show',
+    component: ProductDetailPage,
+    lazy: false,
+    inject: {
+        product: {
+            from: 'productId',
+            resolve: (productId: string) => {
+                return new RouteResourceRequestResolver(
+                    new ProductShowRequest(productId)
+                )
+            }
+        }
+    }
+})
+```
+
+Then use the `useRouteResource` composable inside your component:
+
+```vue
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="error">
+    <p>{{ error.message }}</p>
+    <button @click="refresh">Retry</button>
+  </div>
+  <div v-else>
+    <h1>{{ product.name }}</h1>
+  </div>
+</template>
+
 <script setup lang="ts">
+import { useRouteResource } from '@blueprint-ts/core'
+
 const props = defineProps<{
     product: ProductResource
 }>()
+
+const { refresh, isLoading, error } = useRouteResource('product')
 </script>
 ```
 
-## Handling Loading States
+`useRouteResource` returns:
+
+| Property    | Type                      | Description                              |
+|-------------|---------------------------|------------------------------------------|
+| `isLoading` | `ComputedRef<boolean>`    | `true` while the resource is resolving   |
+| `error`     | `ComputedRef<Error\|null>` | The error if resolution failed, else `null` |
+| `refresh`   | `(options?: { silent?: boolean }) => Promise<void>` | Re-fetches the resource. Pass `{ silent: true }` to suppress the loading state. |
+
+#### Silent Refresh
 
-You can handle the loading state of the request by using the event system of the request class:
+By default, calling `refresh()` sets `isLoading` to `true` while the resource is being re-fetched, which causes `RouteResourceBoundView` to show the loading component. If you want to refresh the resource in the background without triggering the loading state (e.g. polling or optimistic updates), pass `{ silent: true }`:
 
 ```ts
-resolve: (productId: string) => {
-    return new RouteModelRequestResolver(
-        new ProductShowRequest(productId).on<boolean>(RequestEvents.LOADING, (loading: boolean) => {
-          const loadingStore = useLoadingStore()
-          loadingStore.setLoading(loading)
-        })
-    )
-}
-```
+const { refresh } = useRouteResource('product')
+
+// Normal refresh — triggers loading state
+await refresh()
+
+// Silent refresh — does not trigger loading state
+await refresh({ silent: true })
+```
+
+A silent refresh still updates the `error` state if the request fails.
+
+### Lazy vs Non-Lazy
+
+| Option          | Behavior                                                                                      |
+|-----------------|-----------------------------------------------------------------------------------------------|
+| `lazy: true` (default) | `RouteResourceBoundView` intercepts loading/error states and shows the appropriate component |
+| `lazy: false`   | The target component renders immediately; use `useRouteResource()` for manual state handling  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-ts/core",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/vue/router/routeResourceBinding/RouteResourceBoundView.ts

@@ -0,0 +1,145 @@
+import { computed, defineComponent, h, type Component as VueComponent, type VNode } from 'vue'
+import { RouterView, useRoute, type RouteLocationNormalizedLoaded } from 'vue-router'
+
+type InjectionState = Record<string, { loading: boolean; error: Error | null }>
+
+/**
+ * Drop-in replacement for `<router-view>` that handles route resource
+ * injection loading and error states.
+ *
+ * When any injected resource is loading → renders the route's `loadingComponent`.
+ * When any injected resource has an error → renders the route's `errorComponent`
+ *   (receives `error` and `refresh` as props).
+ * Otherwise → passes `{ Component, route }` to the default scoped slot,
+ *   just like `<RouterView>`.
+ *
+ * Error and loading components are defined in the route via `defineRoute`:
+ *
+ * ```ts
+ * defineRoute<{ credential: CredentialResource }>()({
+ *   path: '/credentials/:credentialId',
+ *   component: CredentialShowPage,
+ *   errorComponent: GenericErrorPage,
+ *   loadingComponent: LoadingSpinner,
+ *   inject: {
+ *     credential: {
+ *       from: 'credentialId',
+ *       resolve: (id) => new RouteResourceRequestResolver(new CredentialShowRequest(id)),
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * Set `lazy: false` to render the target component immediately (without
+ * waiting for resources). The component can then handle loading/error
+ * states itself via `useRouteResource()`:
+ *
+ * ```ts
+ * defineRoute<{ credential: CredentialResource }>()({
+ *   path: '/credentials/:credentialId',
+ *   component: CredentialShowPage,
+ *   lazy: false,
+ *   inject: { ... },
+ * })
+ * ```
+ *
+ * Usage in layout (supports the same v-slot pattern as RouterView):
+ * ```vue
+ * <RouteResourceBoundView v-slot="{ Component, route }">
+ *   <component :is="Component" v-if="Component" :key="route.meta.usePathKey ? route.path : undefined" />
+ *   <EmptyState v-else />
+ * </RouteResourceBoundView>
+ * ```
+ *
+ * Or without a slot (renders the matched component automatically):
+ * ```vue
+ * <RouteResourceBoundView />
+ * ```
+ */
+export const RouteResourceBoundView = defineComponent({
+  name: 'RouteResourceBoundView',
+
+  setup(_, { slots }) {
+    const route = useRoute()
+
+    const injectionState = computed(() => {
+      return route.meta._injectionState as InjectionState | undefined
+    })
+
+    const firstError = computed((): Error | null => {
+      const state = injectionState.value
+      if (!state) return null
+
+      for (const key of Object.keys(state)) {
+        const entry = state[key]
+        if (entry?.error) return entry.error
+      }
+
+      return null
+    })
+
+    const anyLoading = computed((): boolean => {
+      const state = injectionState.value
+      if (!state) return false
+
+      return Object.keys(state).some((key) => state[key]?.loading)
+    })
+
+    const refresh = async () => {
+      const state = injectionState.value
+      if (!state) return
+
+      const erroredProps = Object.keys(state).filter((key) => state[key]?.error)
+
+      await Promise.all(erroredProps.map((propName) => route.meta.refresh?.(propName)))
+    }
+
+    /**
+     * Core render logic that decides which slot/component to show
+     * given the resolved Component and route from RouterView.
+     */
+    function renderContent(Component: VueComponent | undefined, resolvedRoute: RouteLocationNormalizedLoaded): VNode | VNode[] | undefined {
+      const isLazy = resolvedRoute.meta._lazy !== false
+
+      if (isLazy) {
+        if (firstError.value) {
+          const errorComponent = resolvedRoute.meta._errorComponent
+
+          if (errorComponent) {
+            return h(errorComponent, { error: firstError.value, refresh })
+          }
+
+          return slots['error']?.({ error: firstError.value, refresh })
+        }
+
+        if (anyLoading.value) {
+          const loadingComponent = resolvedRoute.meta._loadingComponent
+
+          if (loadingComponent) {
+            return h(loadingComponent)
+          }
+
+          return slots['loading']?.()
+        }
+      }
+
+      if (slots['default']) {
+        return slots['default']({ Component, route: resolvedRoute })
+      }
+
+      if (Component) {
+        return h(Component)
+      }
+
+      return undefined
+    }
+
+    return () => {
+      return h(RouterView, null, {
+        default: ({ Component, route: resolvedRoute }: { Component: VueComponent | undefined; route: RouteLocationNormalizedLoaded }) => {
+          return renderContent(Component, resolvedRoute)
+        }
+      })
+    }
+  }
+})

package/src/vue/router/routeResourceBinding/defineRoute.ts

@@ -1,3 +1,4 @@
+import { markRaw, type Component } from 'vue'
 import { type RouteRecordRaw } from 'vue-router'
 import { type InjectConfig } from './types'
 
@@ -7,16 +8,43 @@ import { type InjectConfig } from './types'
  * - inject config types (must resolve Props[K])
  *
  * Usage:
- * export default defineRoute<{ product: ProductResource }>()({ ... })
+ * export default defineRoute<{ product: ProductResource }>()({
+ *   path: '/products/:productId',
+ *   component: ProductShowPage,
+ *   errorComponent: GenericErrorPage,
+ *   loadingComponent: LoadingSpinner,
+ *   inject: { product: { from: 'productId', resolve: ... } },
+ * })
  */
 export function defineRoute<Props extends Record<string, unknown>>() {
   return function <
     T extends RouteRecordRaw & {
       inject?: InjectConfig<Props>
+      errorComponent?: Component
+      loadingComponent?: Component
+      lazy?: boolean
     }
   >(route: T): RouteRecordRaw {
     const originalProps = route.props
 
+    if (route.errorComponent) {
+      route.meta = route.meta ?? {}
+      route.meta._errorComponent = markRaw(route.errorComponent)
+      delete route.errorComponent
+    }
+
+    if (route.loadingComponent) {
+      route.meta = route.meta ?? {}
+      route.meta._loadingComponent = markRaw(route.loadingComponent)
+      delete route.loadingComponent
+    }
+
+    if (route.lazy !== undefined) {
+      route.meta = route.meta ?? {}
+      route.meta._lazy = route.lazy
+      delete route.lazy
+    }
+
     route.props = (to) => {
       const baseProps = typeof originalProps === 'function' ? originalProps(to) : originalProps === true ? to.params : (originalProps ?? {})
 

package/src/vue/router/routeResourceBinding/index.ts

@@ -1,10 +1,11 @@
 import { defineRoute } from './defineRoute'
 import { installRouteInjection } from './installRouteInjection'
+import { RouteResourceBoundView } from './RouteResourceBoundView'
 import { RouteResourceRequestResolver } from './RouteResourceRequestResolver'
 import { useRouteResource } from './useRouteResource'
 
 import type { DataRequest, InjectConfig, Resolver } from './types'
 
-export { defineRoute, installRouteInjection, RouteResourceRequestResolver, useRouteResource }
+export { defineRoute, installRouteInjection, RouteResourceBoundView, RouteResourceRequestResolver, useRouteResource }
 
 export type { DataRequest, InjectConfig, Resolver }

package/src/vue/router/routeResourceBinding/installRouteInjection.ts

@@ -7,17 +7,26 @@ type InjectRuntimeConfig = {
   getter: (payload: unknown) => unknown
 }
 
+type CachedEntry = {
+  paramValue: string
+  payload: unknown
+}
+
 /**
  * Installs the runtime part:
  * - resolves all route.inject entries before navigation completes
  * - stores results on to.meta._injectedProps
  * - ensures route props include injected results (so components receive them as props)
+ * - caches resolved resources so child routes inherit parent-resolved data
+ *   without triggering redundant requests (as long as the param value is unchanged)
  *
  * Notes:
  * - This keeps router files clean: only an `inject` block per route.
  * - This is intentionally runtime-generic; type safety happens at route definition time.
  */
 export function installRouteInjection(router: Router) {
+  const cache: Record<string, CachedEntry> = {}
+
   router.beforeResolve(async (to) => {
     console.log('[Route Injection] Resolving route injections...')
 
@@ -25,7 +34,13 @@ export function installRouteInjection(router: Router) {
       to.meta._injectedProps = reactive({})
     }
 
-    const resolvers: Record<string, () => Promise<unknown>> = {}
+    if (!to.meta._injectionState) {
+      to.meta._injectionState = reactive({})
+    }
+
+    const resolvers: Record<string, (options?: { silent?: boolean }) => Promise<unknown>> = {}
+    const activePropNames = new Set<string>()
+    const pendingResolvers: Array<() => Promise<void>> = []
 
     // Iterate through all matched route records (from parent to child)
     for (const record of to.matched) {
@@ -57,37 +72,93 @@ export function installRouteInjection(router: Router) {
           continue
         }
 
-        // Define the refresh logic for this specific prop
-        const resolveProp = async () => {
-          const resolver = cfg.resolve(paramValue)
-          let payload = await resolver.resolve()
-          if (typeof cfg.getter === 'function') {
-            payload = cfg.getter(payload)
-          }
+        activePropNames.add(propName)
+
+        // Initialize state for this prop
+        const state = to.meta._injectionState as Record<string, { loading: boolean; error: Error | null }>
+        if (!state[propName]) {
+          state[propName] = reactive({ loading: false, error: null })
+        }
 
-          // Updating the reactive object triggers the component re-render
-          ;(to.meta._injectedProps as any)[propName] = payload
-          return payload
+        // Define the refresh logic for this specific prop (always fetches fresh data)
+        const resolveProp = async (options?: { silent?: boolean }) => {
+          const propState = (to.meta._injectionState as Record<string, { loading: boolean; error: Error | null }>)[propName]!
+          if (!options?.silent) {
+            propState.loading = true
+          }
+          propState.error = null
+
+          try {
+            const resolver = cfg.resolve(paramValue)
+            let payload = await resolver.resolve()
+            if (typeof cfg.getter === 'function') {
+              payload = cfg.getter(payload)
+            }
+
+            // Update cache
+            cache[propName] = { paramValue, payload }
+
+            // Updating the reactive object triggers the component re-render
+            const injectedProps = to.meta._injectedProps as Record<string, unknown>
+            injectedProps[propName] = payload
+            return payload
+          } catch (e) {
+            propState.error = e instanceof Error ? e : new Error(String(e))
+            throw e
+          } finally {
+            propState.loading = false
+          }
         }
 
         resolvers[propName] = resolveProp
 
-        await resolveProp()
+        // Reuse cached value if the param hasn't changed (e.g. navigating between child routes)
+        const cached = cache[propName]
+        if (cached && cached.paramValue === paramValue) {
+          console.debug(`[Route Injection] Using cached value for prop "${propName}" (param "${cfg.from}" unchanged)`)
+          const injectedPropsCache = to.meta._injectedProps as Record<string, unknown>
+          injectedPropsCache[propName] = cached.payload
 
-        console.debug(`[Route Injection] Successfully resolved prop "${propName}" for route "${record.path}"`)
+          continue
+        }
+
+        // Set loading immediately and queue resolver (non-blocking)
+        const injectionState = to.meta._injectionState as Record<string, { loading: boolean; error: Error | null }>
+        injectionState[propName]!.loading = true
+        pendingResolvers.push(async () => {
+          try {
+            await resolveProp()
+          } catch (e) {
+            console.error(`[Route Injection] Failed to resolve prop "${propName}"`, e)
+          }
+        })
+
+        console.debug(`[Route Injection] Queued resolution for prop "${propName}" for route "${record.path}"`)
+      }
+    }
+
+    // Evict cache entries that are no longer part of the active route hierarchy
+    for (const key of Object.keys(cache)) {
+      if (!activePropNames.has(key)) {
+        delete cache[key]
       }
     }
 
     // Attach the resolvers and a global refresh helper to the route meta
     to.meta['_injectedResolvers'] = resolvers
-    to.meta['refresh'] = async (propName: string) => {
+    to.meta['refresh'] = async (propName: string, options?: { silent?: boolean }) => {
       if (resolvers[propName]) {
-        return await resolvers[propName]()
+        return await resolvers[propName](options)
       }
 
       console.warn(`[Route Injection] No resolver found for "${propName}"`)
 
       return undefined
     }
+
+    // Fire pending resolvers without blocking navigation
+    if (pendingResolvers.length > 0) {
+      Promise.all(pendingResolvers.map((fn) => fn()))
+    }
   })
 }

package/src/vue/router/routeResourceBinding/types.ts

@@ -1,3 +1,4 @@
+import { type Component } from 'vue'
 import { type RouteLocationNormalized } from 'vue-router'
 
 /**
@@ -42,7 +43,11 @@ declare module 'vue-router' {
   interface RouteMeta {
     _injectedProps?: Record<string, any>
     _injectedResolvers?: Record<string, () => Promise<any>>
-    refresh?: (propName: string) => Promise<any>
+    _injectionState?: Record<string, { loading: boolean; error: Error | null }>
+    _errorComponent?: Component
+    _loadingComponent?: Component
+    _lazy?: boolean
+    refresh?: (propName: string, options?: { silent?: boolean }) => Promise<any>
     inject?: Record<string, unknown>
   }
 }