@quazardous/qdadm 2.1.0 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/entity/EntityManager.cache.ts

@@ -90,7 +90,9 @@ export function applyCacheMethods(EntityManagerClass: { prototype: any }): void
   Object.defineProperty(proto, 'overflow', {
     get(this: Self): boolean {
       const cache = this._cache
-      return cache.valid && cache.total > cache.items.length
+      // overflowed: total exceeded effectiveThreshold, cache was never
+      // filled (#1204) — the cache is unusable either way.
+      return cache.overflowed === true || (cache.valid && cache.total > cache.items.length)
     },
     configurable: true,
   })
@@ -398,6 +400,7 @@ export function applyCacheMethods(EntityManagerClass: { prototype: any }): void
     cache.valid = false
     cache.items = []
     cache.total = 0
+    cache.overflowed = false
     cache.loadedAt = null
     this._cacheLoading = null
     // Also clear detail cache

package/src/entity/EntityManager.crud.ts

@@ -182,6 +182,7 @@ export function applyCrudMethods(EntityManagerClass: { prototype: any }): void {
         cache.items = items
         cache.total = total
         cache.valid = true
+        cache.overflowed = false
         cache.loadedAt = Date.now()
         // Resolve parent fields for search (book.title, user.username, etc.)
         await this._resolveSearchFields(items)
@@ -191,6 +192,11 @@ export function applyCrudMethods(EntityManagerClass: { prototype: any }): void {
         // Fire-and-forget: load full cache in background
         this._loadCacheInBackground()
       }
+    } else if (canUseCache && this.isCacheEnabled && total > this.effectiveThreshold) {
+      // Entity outgrew the threshold: the cache can never hold it. Mark it
+      // so query() stops filtering an empty cache and goes to the API
+      // instead of returning an empty list (#1204).
+      cache.overflowed = true
     }
 
     return { items, total, fromCache: false }

package/src/entity/EntityManager.query.ts

@@ -31,7 +31,7 @@ export function applyQueryMethods(EntityManagerClass: { prototype: any }): void
     // Ensure cache is filled (via list) — skip for dynamic endpoints
     // since list() disables caching when resolveStorage provides an endpoint
     const cache = this._cache
-    if (!isDynamicEndpoint && !cache.valid && this.isCacheEnabled) {
+    if (!isDynamicEndpoint && !cache.valid && !cache.overflowed && this.isCacheEnabled) {
       await this.list(
         { page_size: this.effectiveThreshold },
         routingContext ?? undefined
@@ -40,8 +40,11 @@ export function applyQueryMethods(EntityManagerClass: { prototype: any }): void
 
     let result: ListResult<any>
 
-    // Dynamic endpoint, overflow, or cache disabled → use API directly
-    if (isDynamicEndpoint || this.overflow || !this.isCacheEnabled) {
+    // Dynamic endpoint, overflow, cache disabled, or cache still not
+    // valid (fill failed / threshold exceeded) → use API directly. The
+    // cache is an optional layer: it must never turn into an empty
+    // result when it can't hold the data (#1204).
+    if (isDynamicEndpoint || this.overflow || !this.isCacheEnabled || !cache.valid) {
       result = await this.list(params, routingContext ?? undefined)
     } else {
       // Full cache available - filter locally

package/src/entity/EntityManager.ts

@@ -114,6 +114,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     total: 0,
     loadedAt: null,
     valid: false,
+    overflowed: false,
   }
   protected _cacheLoading: Promise<boolean> | null = null
 

package/src/entity/EntityManager.types.ts

@@ -26,6 +26,8 @@ export interface CacheState<T> {
   total: number
   loadedAt: number | null
   valid: boolean
+  /** Entity total exceeded effectiveThreshold — cache can't hold it (#1204). */
+  overflowed?: boolean
 }
 
 /**

package/src/generated/managers/testManager.ts

@@ -1,46 +0,0 @@
-/**
- * TestManager - Auto-generated EntityManager
- *
- * Generated by qdadm/gen/generateManagers
- * DO NOT EDIT MANUALLY - Changes will be overwritten
- *
- * Entity: test
- * Endpoint: /test
- */
-
-import { EntityManager } from '@quazardous/qdadm'
-import type { EntityRecord } from '@quazardous/qdadm'
-import { ApiStorage } from '@quazardous/qdadm'
-
-export interface TestEntity extends EntityRecord {
-}
-
-/**
- * Schema definition for test
- */
-export const testSchema = {
-  name: "test",
-  endpoint: "/test",
-  fields: {}
-} as const
-
-/**
- * Storage options for test
- */
-const storageOptions = {
-  endpoint: "/test"
-}
-
-/**
- * TestManager instance
- *
- * Provides CRUD operations for test entity.
- */
-export const testManager = new EntityManager<TestEntity>({
-  ...{
-  name: "test",
-  idField: "id",
-  fields: {}
-},
-  storage: new ApiStorage<TestEntity>(storageOptions)
-})

package/src/kernel/Kernel.routing.ts

@@ -212,7 +212,11 @@ export function applyRoutingMethods(KernelClass: { prototype: any }): void {
       }
 
       const entity = to.meta?.entity as string | undefined
-      if (entity && this.orchestrator) {
+      // Entity not registered → nothing to check yet (e.g. child route
+      // declared before its manager loads) — allow. This is the ONLY
+      // allowed pass-through; a failing access check must fail CLOSED,
+      // not silently allow (#1190).
+      if (entity && this.orchestrator && this.orchestrator.isRegistered(entity)) {
         try {
           const manager = this.orchestrator.get(entity)
           if (manager && !manager.canRead()) {
@@ -232,8 +236,13 @@ export function applyRoutingMethods(KernelClass: { prototype: any }): void {
             next({ path: '/' })
             return
           }
-        } catch {
-          // Entity not registered - allow navigation
+        } catch (err) {
+          console.error(
+            `[qdadm] Access check failed for ${to.path} (entity: ${entity}) — denying navigation:`,
+            err
+          )
+          next({ path: '/' })
+          return
         }
       }
 

package/src/kernel/Kernel.types.ts

@@ -192,6 +192,26 @@ export interface KernelOptions {
    * wiring. Typically the same client your ApiStorages use.
    */
   apiClient?: ApiClientSource
+  /**
+   * Naming policy for the URL param carrying the parent id in child route
+   * families (#1201). `auto` (default): list-only families keep the bare
+   * `idField` param; families with show/edit routes namespace the parent
+   * (`jobs/:jobId/tasks/:id`) so the principal (child) id stays `:id`.
+   * `always`: namespaced everywhere. `bare`: legacy `idField` param, with
+   * an explicit registration error on collision.
+   */
+  parentParamMode?: 'auto' | 'always' | 'bare'
+  /**
+   * Global mapping service for parent URL param names (#1201). Consulted
+   * before `parentParamMode`; a per-call `parentParam` still wins. Return
+   * undefined to fall through to the mode-based default.
+   */
+  routeParamResolver?: (ctx: {
+    parentEntity: string
+    parentRouteName: string
+    childEntity: string | null
+    parentIdField: string
+  }) => string | undefined
   /**
    * Existing Vue app to install qdadm onto. When provided, the Kernel
    * skips its own `createApp(WrappedRoot)` and reuses the supplied

package/src/kernel/KernelContext.routing.ts

@@ -45,6 +45,89 @@ function capitalize(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1)
 }
 
+/** Context handed to a kernel-level routeParamResolver (#1201). */
+export interface RouteParamResolverContext {
+  parentEntity: string
+  parentRouteName: string
+  /** Child entity name, or null for a non-entity childPage. */
+  childEntity: string | null
+  parentIdField: string
+}
+
+/**
+ * Resolve the URL param name carrying the parent id in a child route
+ * family (#1201). Precedence: per-call `parentParam` > kernel
+ * `routeParamResolver` > `parentParamMode`:
+ *
+ * - `auto` (default): families whose routes never carry the child's own
+ *   id (list-only, childPage) keep the bare parent `idField` param —
+ *   unchanged URLs. Families with show/edit routes namespace the parent
+ *   (`:jobId`) so the principal (child) id stays `:id`.
+ * - `always`: namespaced parent param everywhere.
+ * - `bare`: legacy `idField` param everywhere; a would-be collision
+ *   throws at registration instead of silently shadowing the parent.
+ */
+function resolveParentParam(opts: {
+  kernelOptions?: {
+    parentParamMode?: 'auto' | 'always' | 'bare'
+    routeParamResolver?: (ctx: RouteParamResolverContext) => string | undefined
+  }
+  explicit?: string
+  parentEntity: string
+  parentRouteName: string
+  childEntity: string | null
+  parentIdField: string
+  childIdParam: string
+  hasOwnIdParam: boolean
+}): string {
+  const {
+    kernelOptions,
+    explicit,
+    parentEntity,
+    parentRouteName,
+    childEntity,
+    parentIdField,
+    childIdParam,
+    hasOwnIdParam,
+  } = opts
+
+  if (explicit) return explicit
+
+  const resolved = kernelOptions?.routeParamResolver?.({
+    parentEntity,
+    parentRouteName,
+    childEntity,
+    parentIdField,
+  })
+  if (resolved) return resolved
+
+  const mode = kernelOptions?.parentParamMode || 'auto'
+  const namespaced = `${singularize(parentEntity)}Id`
+
+  if (mode === 'always') return namespaced
+
+  if (mode === 'bare') {
+    if (hasOwnIdParam && parentIdField === childIdParam) {
+      throw new Error(
+        `[qdadm] crud('${childEntity}', { parentRoute: '${parentRouteName}' }): parent and child ` +
+        `both use the URL param ':${childIdParam}' — the child id would shadow the parent id. ` +
+        `Switch parentParamMode to 'auto', or set an explicit parentParam.`
+      )
+    }
+    return parentIdField
+  }
+
+  // mode === 'auto'
+  if (!hasOwnIdParam) return parentIdField
+  if (namespaced === childIdParam) {
+    throw new Error(
+      `[qdadm] crud('${childEntity}', { parentRoute: '${parentRouteName}' }): the namespaced ` +
+      `parent param ':${namespaced}' collides with the child idField — set an explicit parentParam.`
+    )
+  }
+  return namespaced
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function applyRoutingMethods(KernelContextClass: { prototype: any }): void {
   const proto = KernelContextClass.prototype as Self
@@ -103,7 +186,20 @@ export function applyRoutingMethods(KernelContextClass: { prototype: any }): voi
         const parentManager = parentEntityName
           ? this._kernel.orchestrator?.get(parentEntityName)
           : null
-        const parentIdParam = parentManager?.idField || 'id'
+        const parentIdField = parentManager?.idField || 'id'
+        // Families with show/edit routes carry the child's own :id — the
+        // parent param must not collide with it (#1201).
+        const hasOwnIdParam = !!(pages.show || pages.form || pages.edit)
+        const parentIdParam = resolveParentParam({
+          kernelOptions: this._kernel.options,
+          explicit: options.parentParam,
+          parentEntity: parentEntityName || parentRouteName,
+          parentRouteName,
+          childEntity: entity,
+          parentIdField,
+          childIdParam: idParam,
+          hasOwnIdParam,
+        })
 
         // Build base path: parentPath/:parentId/entity (e.g., books/:bookId/loans)
         const parentBasePath =
@@ -238,7 +334,19 @@ export function applyRoutingMethods(KernelContextClass: { prototype: any }): voi
     const parentManager = parentEntityName
       ? this._kernel.orchestrator?.get(parentEntityName)
       : null
-    const parentIdParam = parentManager?.idField || 'id'
+    const parentIdField = parentManager?.idField || 'id'
+    // childPage has no own :id (single-id family) — auto mode keeps the
+    // bare param; explicit parentParam / resolver / 'always' still apply.
+    const parentIdParam = resolveParentParam({
+      kernelOptions: this._kernel.options,
+      explicit: options.parentParam,
+      parentEntity: parentEntityName || parentRouteName,
+      parentRouteName,
+      childEntity: null,
+      parentIdField,
+      childIdParam: 'id',
+      hasOwnIdParam: false,
+    })
 
     const parentBasePath =
       parentRoute.path.replace(/\/(create|:.*)?$/, '') || parentEntityName

package/src/kernel/KernelContext.types.ts

@@ -148,6 +148,12 @@ export interface CrudOptions {
   parentRoute?: string
   foreignKey?: string
   label?: string
+  /**
+   * Explicit URL param name carrying the parent id in child routes
+   * (e.g. 'jobUuid' → `jobs/:jobUuid/tasks/:id`). Overrides the kernel
+   * `routeParamResolver` and `parentParamMode` (#1201).
+   */
+  parentParam?: string
 }
 
 /** Child page options for non-entity child routes */
@@ -156,6 +162,8 @@ export interface ChildPageOptions {
   label?: string
   icon?: string
   meta?: Record<string, unknown>
+  /** Explicit URL param name for the parent id (see CrudOptions.parentParam). */
+  parentParam?: string
 }
 
 /** User entity options */