@blueprint-ts/core 1.1.2 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 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)
+
+
+### Features
+
+* Added state paginator feature 87a9466
 ## v1.1.2 - 2026-01-09
 
 ## [1.1.2](/compare/v1.1.1...v1.1.2) (2026-01-09)

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.1.2",
+  "version": "2.0.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/service/pagination/BasePaginator.ts

@@ -0,0 +1,36 @@
+import { PaginationDataDto } from './dtos/PaginationDataDto'
+import { type BaseViewDriverContract } from './contracts/BaseViewDriverContract'
+import { type PaginatorLoadDataOptions } from './contracts/PaginatorLoadDataOptions'
+
+export abstract class BasePaginator<ResourceInterface, ViewDriver extends BaseViewDriverContract<ResourceInterface[]>> {
+  protected initialized: boolean = false
+
+  protected abstract viewDriver: ViewDriver
+
+  public constructor(protected dataDriver: unknown) {}
+
+  public isInitialized(): boolean {
+    return this.initialized
+  }
+
+  public flush(): void {
+    this.viewDriver.setData([])
+  }
+
+  public getPageData(): ResourceInterface[] {
+    return this.viewDriver.getData()
+  }
+
+  public getTotal(): number {
+    return this.viewDriver.getTotal()
+  }
+
+  protected passDataToViewDriver(dto: PaginationDataDto<ResourceInterface[]>, options?: PaginatorLoadDataOptions): void {
+    if (options?.flush) {
+      this.flush()
+    }
+
+    this.viewDriver.setData(dto.getData())
+    this.viewDriver.setTotal(dto.getTotal())
+  }
+}

package/src/service/pagination/InfiniteScroller.ts

@@ -1,8 +1,8 @@
-import { Paginator } from './Paginator'
+import { PageAwarePaginator } from './PageAwarePaginator'
 import { PaginationDataDto } from './dtos/PaginationDataDto'
 import { type PaginatorLoadDataOptions } from './contracts/PaginatorLoadDataOptions'
 
-export class InfiniteScroller<ResourceInterface> extends Paginator<ResourceInterface> {
+export class InfiniteScroller<ResourceInterface> extends PageAwarePaginator<ResourceInterface> {
   protected override passDataToViewDriver(dto: PaginationDataDto<ResourceInterface[]>, options: PaginatorLoadDataOptions = {}) {
     const { flush = false, replace = false } = options
 

package/src/service/pagination/PageAwarePaginator.ts

@@ -0,0 +1,124 @@
+import { PaginationDataDto } from './dtos/PaginationDataDto'
+import { type ViewDriverContract } from './contracts/ViewDriverContract'
+import { type ViewDriverFactoryContract } from './contracts/ViewDriverFactoryContract'
+import { type PaginatorLoadDataOptions } from './contracts/PaginatorLoadDataOptions'
+import { type PaginationDataDriverContract } from './contracts/PaginationDataDriverContract'
+import { BasePaginator } from './BasePaginator'
+
+export interface PageAwarePaginatorOptions {
+  viewDriverFactory?: ViewDriverFactoryContract
+}
+
+export class PageAwarePaginator<ResourceInterface> extends BasePaginator<ResourceInterface, ViewDriverContract<ResourceInterface[]>> {
+  protected static viewDriverFactory: ViewDriverFactoryContract
+
+  protected override viewDriver: ViewDriverContract<ResourceInterface[]>
+
+  public static setViewDriverFactory(value: ViewDriverFactoryContract): void {
+    PageAwarePaginator.viewDriverFactory = value
+  }
+
+  public constructor(
+    protected override dataDriver: PaginationDataDriverContract<ResourceInterface[]>,
+    pageNumber: number = 1,
+    pageSize: number = 10,
+    options?: PageAwarePaginatorOptions
+  ) {
+    super(dataDriver)
+    this.viewDriver = options?.viewDriverFactory
+      ? options.viewDriverFactory.make<ResourceInterface>(pageNumber, pageSize)
+      : PageAwarePaginator.viewDriverFactory.make<ResourceInterface>(pageNumber, pageSize)
+  }
+
+  public setDataDriver(dataDriver: PaginationDataDriverContract<ResourceInterface[]>): this {
+    this.dataDriver = dataDriver
+
+    return this
+  }
+
+  public getDataDriver(): PaginationDataDriverContract<ResourceInterface[]> {
+    return this.dataDriver
+  }
+
+  public init(pageNumber: number, pageSize: number): Promise<PaginationDataDto<ResourceInterface[]>> {
+    this.initialized = true
+
+    if (pageNumber && pageSize) {
+      return this.loadData(pageNumber, pageSize)
+    }
+
+    return this.loadData(this.getCurrentPage(), this.getPageSize())
+  }
+
+  public refresh(pageNumber?: number, options?: PaginatorLoadDataOptions): Promise<PaginationDataDto<ResourceInterface[]>> {
+    if (pageNumber !== undefined) {
+      return this.setPage(pageNumber, options)
+    }
+
+    return this.loadData(this.getCurrentPage(), this.getPageSize(), options)
+  }
+
+  public setPage(pageNumber: number, options?: PaginatorLoadDataOptions): Promise<PaginationDataDto<ResourceInterface[]>> {
+    this.viewDriver.setPage(pageNumber)
+
+    return this.loadData(this.viewDriver.getCurrentPage(), this.viewDriver.getPageSize(), options)
+  }
+
+  public getLastPage(): number {
+    return this.viewDriver.getLastPage()
+  }
+
+  public toNextPage(): Promise<PaginationDataDto<ResourceInterface[]>> {
+    return this.setPage(this.getCurrentPage() + 1)
+  }
+
+  public toFirstPage(): Promise<PaginationDataDto<ResourceInterface[]>> {
+    return this.setPage(1)
+  }
+
+  public toLastPage(): Promise<PaginationDataDto<ResourceInterface[]>> {
+    return this.setPage(this.viewDriver.getLastPage())
+  }
+
+  public toPreviousPage(): Promise<PaginationDataDto<ResourceInterface[]>> {
+    return this.setPage(this.getCurrentPage() - 1)
+  }
+
+  public getCurrentPage(): number {
+    return this.viewDriver.getCurrentPage()
+  }
+
+  public getFromItemNumber(): number {
+    return (this.getCurrentPage() - 1) * this.getPageSize() + 1
+  }
+
+  public getToItemNumber(): number {
+    return this.getCurrentPage() * this.getPageSize()
+  }
+
+  public getPageSize(): number {
+    return this.viewDriver.getPageSize()
+  }
+
+  public setPageSize(pageSize: number): Promise<PaginationDataDto<ResourceInterface[]>> {
+    this.viewDriver.setPageSize(pageSize)
+
+    if (this.getCurrentPage() * pageSize > this.getTotal()) {
+      return this.setPage(1)
+    }
+
+    return this.loadData(this.viewDriver.getCurrentPage(), this.viewDriver.getPageSize())
+  }
+
+  public getPages(): number[] {
+    return this.viewDriver.getPages()
+  }
+
+  protected loadData(pageNumber: number, pageSize: number, options?: PaginatorLoadDataOptions): Promise<PaginationDataDto<ResourceInterface[]>> {
+    return this.dataDriver.get(pageNumber, pageSize).then((value: PaginationDataDto<ResourceInterface[]>) => {
+      this.passDataToViewDriver(value, options)
+
+      return value
+    })
+  }
+}

package/src/service/pagination/Paginator.ts

@@ -1,149 +1,11 @@
-import { PaginationDataDto } from './dtos/PaginationDataDto'
-import { type ViewDriverContract } from './contracts/ViewDriverContract'
-import { type ViewDriverFactoryContract } from './contracts/ViewDriverFactoryContract'
-import { type PaginatorLoadDataOptions } from './contracts/PaginatorLoadDataOptions'
-import { type PaginationDataDriverContract } from './contracts/PaginationDataDriverContract'
+import { PageAwarePaginator, type PageAwarePaginatorOptions } from './PageAwarePaginator'
 
-export interface PaginatorOptions {
-  viewDriverFactory?: ViewDriverFactoryContract
-}
+/**
+ * @deprecated Use PageAwarePaginator instead. This alias is kept for backward compatibility.
+ */
+export const Paginator = PageAwarePaginator
 
-export class Paginator<ResourceInterface> {
-  protected initialized: boolean = false
-
-  protected static viewDriverFactory: ViewDriverFactoryContract
-
-  protected viewDriver: ViewDriverContract<ResourceInterface[]>
-
-  public static setViewDriverFactory(value: ViewDriverFactoryContract): void {
-    Paginator.viewDriverFactory = value
-  }
-
-  public constructor(
-    protected dataDriver: PaginationDataDriverContract<ResourceInterface[]>,
-    pageNumber: number = 1,
-    pageSize: number = 10,
-    options?: PaginatorOptions
-  ) {
-    this.viewDriver = options?.viewDriverFactory
-      ? options.viewDriverFactory.make<ResourceInterface>(pageNumber, pageSize)
-      : Paginator.viewDriverFactory.make<ResourceInterface>(pageNumber, pageSize)
-  }
-
-  public setDataDriver(dataDriver: PaginationDataDriverContract<ResourceInterface[]>): this {
-    this.dataDriver = dataDriver
-
-    return this
-  }
-
-  public getDataDriver(): PaginationDataDriverContract<ResourceInterface[]> {
-    return this.dataDriver
-  }
-
-  public init(pageNumber: number, pageSize: number): Promise<PaginationDataDto<ResourceInterface[]>> {
-    this.initialized = true
-
-    if (pageNumber && pageSize) {
-      return this.loadData(pageNumber, pageSize)
-    }
-
-    return this.loadData(this.getCurrentPage(), this.getPageSize())
-  }
-
-  public refresh(pageNumber?: number, options?: PaginatorLoadDataOptions): Promise<PaginationDataDto<ResourceInterface[]>> {
-    if (pageNumber !== undefined) {
-      return this.setPage(pageNumber, options)
-    }
-
-    return this.loadData(this.getCurrentPage(), this.getPageSize(), options)
-  }
-
-  public flush(): void {
-    this.viewDriver.setData([])
-  }
-
-  public setPage(pageNumber: number, options?: PaginatorLoadDataOptions): Promise<PaginationDataDto<ResourceInterface[]>> {
-    this.viewDriver.setPage(pageNumber)
-
-    return this.loadData(this.viewDriver.getCurrentPage(), this.viewDriver.getPageSize(), options)
-  }
-
-  public isInitialized(): boolean {
-    return this.initialized
-  }
-
-  public getLastPage(): number {
-    return this.viewDriver.getLastPage()
-  }
-
-  public toNextPage(): Promise<PaginationDataDto<ResourceInterface[]>> {
-    return this.setPage(this.getCurrentPage() + 1)
-  }
-
-  public toFirstPage(): Promise<PaginationDataDto<ResourceInterface[]>> {
-    return this.setPage(1)
-  }
-
-  public toLastPage(): Promise<PaginationDataDto<ResourceInterface[]>> {
-    return this.setPage(this.viewDriver.getLastPage())
-  }
-
-  public toPreviousPage(): Promise<PaginationDataDto<ResourceInterface[]>> {
-    return this.setPage(this.getCurrentPage() - 1)
-  }
-
-  public getPageData(): ResourceInterface[] {
-    return this.viewDriver.getData()
-  }
-
-  public getCurrentPage(): number {
-    return this.viewDriver.getCurrentPage()
-  }
-
-  public getFromItemNumber(): number {
-    return (this.getCurrentPage() - 1) * this.getPageSize() + 1
-  }
-
-  public getToItemNumber(): number {
-    return this.getCurrentPage() * this.getPageSize()
-  }
-
-  public getTotal(): number {
-    return this.viewDriver.getTotal()
-  }
-
-  public getPageSize(): number {
-    return this.viewDriver.getPageSize()
-  }
-
-  public setPageSize(pageSize: number): Promise<PaginationDataDto<ResourceInterface[]>> {
-    this.viewDriver.setPageSize(pageSize)
-
-    if (this.getCurrentPage() * pageSize > this.getTotal()) {
-      return this.setPage(1)
-    }
-
-    return this.loadData(this.viewDriver.getCurrentPage(), this.viewDriver.getPageSize())
-  }
-
-  public getPages(): number[] {
-    return this.viewDriver.getPages()
-  }
-
-  protected loadData(pageNumber: number, pageSize: number, options?: PaginatorLoadDataOptions): Promise<PaginationDataDto<ResourceInterface[]>> {
-    return this.dataDriver.get(pageNumber, pageSize).then((value: PaginationDataDto<ResourceInterface[]>) => {
-      this.passDataToViewDriver(value, options)
-
-      return value
-    })
-  }
-
-  protected passDataToViewDriver(dto: PaginationDataDto<ResourceInterface[]>, options?: PaginatorLoadDataOptions): void {
-    if (options?.flush) {
-      this.flush()
-    }
-
-    this.viewDriver.setData(dto.getData())
-    this.viewDriver.setTotal(dto.getTotal())
-  }
-}
+/**
+ * @deprecated Use PageAwarePaginatorOptions instead. This alias is kept for backward compatibility.
+ */
+export type PaginatorOptions = PageAwarePaginatorOptions