@blueprint-ts/core 1.1.2 → 2.0.0

package/src/service/pagination/StatePaginator.ts

@@ -0,0 +1,92 @@
+import { StatePaginationDataDto } from './dtos/StatePaginationDataDto'
+import { type BaseViewDriverContract } from './contracts/BaseViewDriverContract'
+import { type BaseViewDriverFactoryContract } from './contracts/BaseViewDriverFactoryContract'
+import { type PaginatorLoadDataOptions } from './contracts/PaginatorLoadDataOptions'
+import { type StatePaginationDataDriverContract } from './contracts/StatePaginationDataDriverContract'
+import { BasePaginator } from './BasePaginator'
+
+export interface StatePaginatorOptions {
+  viewDriverFactory?: BaseViewDriverFactoryContract
+}
+
+export class StatePaginator<ResourceInterface> extends BasePaginator<ResourceInterface, BaseViewDriverContract<ResourceInterface[]>> {
+  protected static viewDriverFactory: BaseViewDriverFactoryContract
+
+  protected override viewDriver: BaseViewDriverContract<ResourceInterface[]>
+
+  protected currentState: string | null = null
+
+  public static setViewDriverFactory(value: BaseViewDriverFactoryContract): void {
+    StatePaginator.viewDriverFactory = value
+  }
+
+  public constructor(
+    protected override dataDriver: StatePaginationDataDriverContract<ResourceInterface[]>,
+    options?: StatePaginatorOptions
+  ) {
+    super(dataDriver)
+    this.viewDriver = options?.viewDriverFactory
+      ? options.viewDriverFactory.make<ResourceInterface>()
+      : StatePaginator.viewDriverFactory.make<ResourceInterface>()
+  }
+
+  public setDataDriver(dataDriver: StatePaginationDataDriverContract<ResourceInterface[]>): this {
+    this.dataDriver = dataDriver
+
+    return this
+  }
+
+  public getDataDriver(): StatePaginationDataDriverContract<ResourceInterface[]> {
+    return this.dataDriver
+  }
+
+  public init(): Promise<StatePaginationDataDto<ResourceInterface[]>> {
+    this.initialized = true
+    this.currentState = null
+
+    return this.loadData()
+  }
+
+  public refresh(options?: PaginatorLoadDataOptions): Promise<StatePaginationDataDto<ResourceInterface[]>> {
+    this.currentState = null
+
+    return this.loadData({ ...options, flush: true })
+  }
+
+  public loadNext(): Promise<StatePaginationDataDto<ResourceInterface[]>> {
+    return this.loadData()
+  }
+
+  public hasNextPage(): boolean {
+    return this.currentState !== null
+  }
+
+  public getCurrentState(): string | null {
+    return this.currentState
+  }
+
+  protected loadData(options?: PaginatorLoadDataOptions): Promise<StatePaginationDataDto<ResourceInterface[]>> {
+    return this.dataDriver.get(this.currentState).then((value: StatePaginationDataDto<ResourceInterface[]>) => {
+      this.currentState = value.getState()
+      this.passStateDataToViewDriver(value, options)
+
+      return value
+    })
+  }
+
+  protected passStateDataToViewDriver(dto: StatePaginationDataDto<ResourceInterface[]>, options?: PaginatorLoadDataOptions): void {
+    const { flush = false, replace = false } = options || {}
+
+    if (flush) {
+      this.flush()
+    }
+
+    if (replace) {
+      this.viewDriver.setData(dto.getData())
+    } else {
+      this.viewDriver.setData(this.viewDriver.getData().concat(dto.getData()))
+    }
+
+    this.viewDriver.setTotal(dto.getTotal())
+  }
+}

package/src/service/pagination/contracts/BaseViewDriverContract.ts

@@ -0,0 +1,6 @@
+export interface BaseViewDriverContract<ResourceInterface> {
+  setData(data: ResourceInterface): void
+  getData(): ResourceInterface
+  setTotal(value: number): void
+  getTotal(): number
+}

package/src/service/pagination/contracts/BaseViewDriverFactoryContract.ts

@@ -0,0 +1,5 @@
+import { type BaseViewDriverContract } from './BaseViewDriverContract'
+
+export interface BaseViewDriverFactoryContract {
+  make<ResourceInterface>(): BaseViewDriverContract<ResourceInterface[]>
+}

package/src/service/pagination/contracts/StatePaginationDataDriverContract.ts

@@ -0,0 +1,5 @@
+import { StatePaginationDataDto } from '../dtos/StatePaginationDataDto'
+
+export interface StatePaginationDataDriverContract<ResourceInterface> {
+  get(state?: string | null): Promise<StatePaginationDataDto<ResourceInterface>>
+}

package/src/service/pagination/contracts/ViewDriverContract.ts

@@ -1,12 +1,10 @@
-export interface ViewDriverContract<ResourceInterface> {
-  setData(data: ResourceInterface): void
-  setTotal(value: number): void
-  getData(): ResourceInterface
+import { type BaseViewDriverContract } from './BaseViewDriverContract'
+
+export interface ViewDriverContract<ResourceInterface> extends BaseViewDriverContract<ResourceInterface> {
   getCurrentPage(): number
   setPage(value: number): void
   setPageSize(value: number): void
   getPageSize(): number
   getLastPage(): number
   getPages(): number[]
-  getTotal(): number
 }

package/src/service/pagination/dtos/StatePaginationDataDto.ts

@@ -0,0 +1,19 @@
+import { PaginationDataDto } from './PaginationDataDto'
+
+export class StatePaginationDataDto<ResourceInterface> extends PaginationDataDto<ResourceInterface> {
+  public constructor(
+    data: ResourceInterface,
+    total: number,
+    protected state: string | null = null
+  ) {
+    super(data, total)
+  }
+
+  public getState(): string | null {
+    return this.state
+  }
+
+  public hasNextPage(): boolean {
+    return this.state !== null
+  }
+}

package/src/service/pagination/factories/VueBaseViewDriverFactory.ts

@@ -0,0 +1,9 @@
+import { type BaseViewDriverFactoryContract } from '../contracts/BaseViewDriverFactoryContract'
+import { type BaseViewDriverContract } from '../contracts/BaseViewDriverContract'
+import { VueBaseViewDriver } from '../frontendDrivers/VueBaseViewDriver'
+
+export class VueBaseViewDriverFactory implements BaseViewDriverFactoryContract {
+  public make<ResourceInterface>(): BaseViewDriverContract<ResourceInterface[]> {
+    return new VueBaseViewDriver<ResourceInterface>()
+  }
+}

package/src/service/pagination/frontendDrivers/VueBaseViewDriver.ts

@@ -0,0 +1,28 @@
+import { ref, type Ref } from 'vue'
+import { type BaseViewDriverContract } from '../contracts/BaseViewDriverContract'
+
+export class VueBaseViewDriver<ResourceInterface> implements BaseViewDriverContract<ResourceInterface[]> {
+  protected dataRef: Ref<ResourceInterface[]>
+  protected totalRef: Ref<number>
+
+  public constructor() {
+    this.dataRef = ref([]) as Ref<ResourceInterface[]>
+    this.totalRef = ref<number>(0)
+  }
+
+  public setData(data: ResourceInterface[]): void {
+    this.dataRef.value = data
+  }
+
+  public getData(): ResourceInterface[] {
+    return this.dataRef.value
+  }
+
+  public setTotal(value: number): void {
+    this.totalRef.value = value
+  }
+
+  public getTotal(): number {
+    return this.totalRef.value
+  }
+}

package/src/service/pagination/index.ts

@@ -1,16 +1,48 @@
 import { PaginationDataDto } from './dtos/PaginationDataDto'
+import { StatePaginationDataDto } from './dtos/StatePaginationDataDto'
 import { VuePaginationDriver } from './frontendDrivers/VuePaginationDriver'
+import { VueBaseViewDriver } from './frontendDrivers/VueBaseViewDriver'
 import { Paginator } from './Paginator'
+import { BasePaginator } from './BasePaginator'
+import { PageAwarePaginator } from './PageAwarePaginator'
+import { StatePaginator } from './StatePaginator'
 import { InfiniteScroller } from './InfiniteScroller'
 import { VuePaginationDriverFactory } from './factories/VuePaginationDriverFactory'
+import { VueBaseViewDriverFactory } from './factories/VueBaseViewDriverFactory'
 import { type PaginateableRequestContract } from './contracts/PaginateableRequestContract'
 import { type PaginationResponseContract } from './contracts/PaginationResponseContract'
 import { type PaginationDataDriverContract } from './contracts/PaginationDataDriverContract'
+import { type StatePaginationDataDriverContract } from './contracts/StatePaginationDataDriverContract'
 import { getDisplayablePages } from '../../helpers'
 import { ArrayDriver } from './dataDrivers/ArrayDriver'
+import { type BaseViewDriverContract } from './contracts/BaseViewDriverContract'
 import { type ViewDriverContract } from './contracts/ViewDriverContract'
+import { type BaseViewDriverFactoryContract } from './contracts/BaseViewDriverFactoryContract'
 import { type ViewDriverFactoryContract } from './contracts/ViewDriverFactoryContract'
 
-export { PaginationDataDto, VuePaginationDriver, Paginator, InfiniteScroller, VuePaginationDriverFactory, getDisplayablePages, ArrayDriver }
+export {
+  PaginationDataDto,
+  StatePaginationDataDto,
+  VuePaginationDriver,
+  VueBaseViewDriver,
+  Paginator,
+  BasePaginator,
+  PageAwarePaginator,
+  StatePaginator,
+  InfiniteScroller,
+  VuePaginationDriverFactory,
+  VueBaseViewDriverFactory,
+  getDisplayablePages,
+  ArrayDriver
+}
 
-export type { PaginationDataDriverContract, PaginationResponseContract, PaginateableRequestContract, ViewDriverContract, ViewDriverFactoryContract }
+export type {
+  PaginationDataDriverContract,
+  StatePaginationDataDriverContract,
+  PaginationResponseContract,
+  PaginateableRequestContract,
+  BaseViewDriverContract,
+  ViewDriverContract,
+  BaseViewDriverFactoryContract,
+  ViewDriverFactoryContract
+}

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>
   }
 }

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

@@ -1,14 +1,24 @@
+import { computed, type ComputedRef } from 'vue'
 import { useRoute } from 'vue-router'
 
-export function useRouteResource() {
+type InjectionState = Record<string, { loading: boolean; error: Error | null }>
+
+export function useRouteResource(propName: string) {
   const route = useRoute()
 
-  const refresh = async (propName: string) => {
-    return await route.meta.refresh?.(propName)
+  const refresh = async (options?: { silent?: boolean }) => {
+    return await route.meta.refresh?.(propName, options)
   }
 
-  // If emit is passed, we can wrap it or just provide a helper
-  // to be used like: onRefresh('product', () => ...)
-  // but the most direct way for you is:
-  return { refresh }
+  const isLoading: ComputedRef<boolean> = computed(() => {
+    const state = route.meta._injectionState as InjectionState | undefined
+    return state?.[propName]?.loading ?? false
+  })
+
+  const error: ComputedRef<Error | null> = computed(() => {
+    const state = route.meta._injectionState as InjectionState | undefined
+    return state?.[propName]?.error ?? null
+  })
+
+  return { refresh, isLoading, error }
 }