qdadm 0.27.0 → 0.28.0

package/package.json

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

package/src/composables/index.js

@@ -21,3 +21,4 @@ export { useZoneRegistry } from './useZoneRegistry'
 export { useHooks } from './useHooks'
 export { useLayoutResolver, createLayoutComponents, layoutMeta, LAYOUT_TYPES } from './useLayoutResolver'
 export { useSSE } from './useSSE'
+export { useDeferred, useDeferredValue, DEFERRED_INJECTION_KEY } from './useDeferred'

package/src/composables/useDeferred.js

@@ -0,0 +1,85 @@
+/**
+ * useDeferred - Access the DeferredRegistry from components
+ *
+ * Provides loose async coupling between services and components.
+ * Components can await dependencies without knowing when they're loaded.
+ *
+ * @example
+ * ```js
+ * import { useDeferred } from 'qdadm/composables'
+ *
+ * // In a component
+ * const deferred = useDeferred()
+ *
+ * // Await a single dependency
+ * const config = await deferred.await('config')
+ *
+ * // Await multiple dependencies
+ * const [users, settings] = await Promise.all([
+ *   deferred.await('users-service'),
+ *   deferred.await('settings')
+ * ])
+ *
+ * // Check status without waiting
+ * if (deferred.isSettled('config')) {
+ *   const config = deferred.value('config')
+ * }
+ * ```
+ */
+
+import { inject } from 'vue'
+
+/**
+ * Injection key for DeferredRegistry
+ */
+export const DEFERRED_INJECTION_KEY = 'qdadmDeferred'
+
+/**
+ * Get the DeferredRegistry instance
+ * @returns {import('../deferred/DeferredRegistry.js').DeferredRegistry}
+ */
+export function useDeferred() {
+  const deferred = inject(DEFERRED_INJECTION_KEY)
+
+  if (!deferred) {
+    throw new Error(
+      '[useDeferred] DeferredRegistry not found. ' +
+      'Make sure you are using the Kernel to bootstrap your app.'
+    )
+  }
+
+  return deferred
+}
+
+/**
+ * Helper: await a deferred value in setup
+ * Returns a ref that updates when the deferred resolves
+ *
+ * @example
+ * ```js
+ * const { data: config, loading, error } = useDeferredValue('config')
+ * ```
+ *
+ * @param {string} key - Deferred key
+ * @returns {{ data: Ref, loading: Ref<boolean>, error: Ref<Error|null> }}
+ */
+export function useDeferredValue(key) {
+  const deferred = useDeferred()
+  const data = ref(null)
+  const loading = ref(true)
+  const error = ref(null)
+
+  deferred.await(key)
+    .then(value => {
+      data.value = value
+      loading.value = false
+    })
+    .catch(err => {
+      error.value = err
+      loading.value = false
+    })
+
+  return { data, loading, error }
+}
+
+import { ref } from 'vue'

package/src/composables/useListPageBuilder.js

@@ -994,6 +994,9 @@ export function useListPageBuilder(config = {}) {
   const displayItems = computed(() => filteredItems.value)
 
   // ============ LOADING ============
+  // Note: Auth changes are handled by Vue component lifecycle - when user logs out,
+  // router guard redirects to login, component unmounts. On re-login, new component
+  // instance is created with fresh state (filterOptionsLoaded = false).
   let filterOptionsLoaded = false
 
   async function loadItems(extraParams = {}, { force = false } = {}) {

package/src/deferred/DeferredRegistry.js

@@ -0,0 +1,323 @@
+/**
+ * DeferredRegistry - Named promise registry for loose coupling
+ *
+ * Enables async dependencies between services/components:
+ * - Services queue work during warmup
+ * - Components await dependencies without tight coupling
+ * - External signals (SSE) can resolve promises
+ *
+ * Key insight: await() can be called BEFORE queue() - the promise
+ * is created on first access and resolved when the task completes.
+ *
+ * @example
+ * ```js
+ * // During app boot - queue lazy services
+ * deferred.queue('users-service', () => usersService.init())
+ * deferred.queue('config', () => configService.load())
+ *
+ * // In component - await dependencies (can be called before queue!)
+ * const config = await deferred.await('config')
+ *
+ * // Wait for multiple with Promise.all
+ * const [users, config] = await Promise.all([
+ *   deferred.await('users-service'),
+ *   deferred.await('config')
+ * ])
+ *
+ * // External resolution (SSE, webhooks)
+ * deferred.resolve('job-123', { status: 'done', data: result })
+ * deferred.reject('job-456', new Error('Failed'))
+ * ```
+ */
+
+/**
+ * @typedef {'pending' | 'running' | 'completed' | 'failed'} DeferredStatus
+ */
+
+/**
+ * @typedef {object} DeferredEntry
+ * @property {Promise} promise - The deferred promise
+ * @property {function} resolve - Resolve function
+ * @property {function} reject - Reject function
+ * @property {DeferredStatus} status - Current status
+ * @property {any} value - Resolved value or error
+ * @property {number} timestamp - Creation timestamp
+ */
+
+export class DeferredRegistry {
+  /**
+   * @param {object} options
+   * @param {object} [options.kernel] - Optional QuarKernel for event emission
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(options = {}) {
+    this._entries = new Map()
+    this._kernel = options.kernel || null
+    this._debug = options.debug || false
+  }
+
+  /**
+   * Get or create a deferred entry for a key
+   * @param {string} key - Unique identifier
+   * @returns {DeferredEntry}
+   */
+  _getOrCreate(key) {
+    if (!this._entries.has(key)) {
+      let resolve, reject
+      const promise = new Promise((res, rej) => {
+        resolve = res
+        reject = rej
+      })
+
+      const entry = {
+        promise,
+        resolve,
+        reject,
+        status: 'pending',
+        value: undefined,
+        timestamp: Date.now()
+      }
+
+      this._entries.set(key, entry)
+
+      if (this._debug) {
+        console.debug(`[deferred] Created entry: ${key}`)
+      }
+    }
+
+    return this._entries.get(key)
+  }
+
+  /**
+   * Get the promise for a key (creates if doesn't exist)
+   * Can be called BEFORE queue() - promise resolves when task completes
+   *
+   * @param {string} key - Unique identifier
+   * @returns {Promise<any>}
+   */
+  await(key) {
+    return this._getOrCreate(key).promise
+  }
+
+  /**
+   * Queue a task for execution
+   * If already running/completed, returns existing promise (deduplication)
+   *
+   * @param {string} key - Unique identifier
+   * @param {function(): Promise<any>} executor - Async function to execute
+   * @returns {Promise<any>} Promise that resolves with task result
+   */
+  queue(key, executor) {
+    const entry = this._getOrCreate(key)
+
+    // Already started - return existing promise (idempotent)
+    if (entry.status !== 'pending') {
+      if (this._debug) {
+        console.debug(`[deferred] Already ${entry.status}: ${key}`)
+      }
+      return entry.promise
+    }
+
+    entry.status = 'running'
+    this._emit('deferred:started', { key })
+
+    if (this._debug) {
+      console.debug(`[deferred] Started: ${key}`)
+    }
+
+    // Execute and handle result
+    Promise.resolve()
+      .then(() => executor())
+      .then(value => {
+        entry.status = 'completed'
+        entry.value = value
+        entry.resolve(value)
+        this._emit('deferred:completed', { key, value })
+
+        if (this._debug) {
+          console.debug(`[deferred] Completed: ${key}`)
+        }
+      })
+      .catch(error => {
+        entry.status = 'failed'
+        entry.value = error
+        entry.reject(error)
+        this._emit('deferred:failed', { key, error })
+
+        if (this._debug) {
+          console.debug(`[deferred] Failed: ${key}`, error)
+        }
+      })
+
+    return entry.promise
+  }
+
+  /**
+   * Resolve a deferred externally (for SSE, webhooks, etc.)
+   * No-op if already completed/failed
+   *
+   * @param {string} key - Unique identifier
+   * @param {any} value - Value to resolve with
+   * @returns {boolean} True if resolved, false if already settled
+   */
+  resolve(key, value) {
+    const entry = this._getOrCreate(key)
+
+    if (entry.status === 'completed' || entry.status === 'failed') {
+      if (this._debug) {
+        console.debug(`[deferred] Cannot resolve (already ${entry.status}): ${key}`)
+      }
+      return false
+    }
+
+    entry.status = 'completed'
+    entry.value = value
+    entry.resolve(value)
+    this._emit('deferred:completed', { key, value })
+
+    if (this._debug) {
+      console.debug(`[deferred] Resolved externally: ${key}`)
+    }
+
+    return true
+  }
+
+  /**
+   * Reject a deferred externally (for SSE, webhooks, etc.)
+   * No-op if already completed/failed
+   *
+   * @param {string} key - Unique identifier
+   * @param {Error} error - Error to reject with
+   * @returns {boolean} True if rejected, false if already settled
+   */
+  reject(key, error) {
+    const entry = this._getOrCreate(key)
+
+    if (entry.status === 'completed' || entry.status === 'failed') {
+      if (this._debug) {
+        console.debug(`[deferred] Cannot reject (already ${entry.status}): ${key}`)
+      }
+      return false
+    }
+
+    entry.status = 'failed'
+    entry.value = error
+    entry.reject(error)
+    this._emit('deferred:failed', { key, error })
+
+    if (this._debug) {
+      console.debug(`[deferred] Rejected externally: ${key}`)
+    }
+
+    return true
+  }
+
+  /**
+   * Check if a key exists in the registry
+   * @param {string} key
+   * @returns {boolean}
+   */
+  has(key) {
+    return this._entries.has(key)
+  }
+
+  /**
+   * Get the status of a deferred
+   * @param {string} key
+   * @returns {DeferredStatus|null} Status or null if not found
+   */
+  status(key) {
+    return this._entries.get(key)?.status || null
+  }
+
+  /**
+   * Get the resolved value (only if completed)
+   * @param {string} key
+   * @returns {any} Value or undefined
+   */
+  value(key) {
+    const entry = this._entries.get(key)
+    return entry?.status === 'completed' ? entry.value : undefined
+  }
+
+  /**
+   * Check if a deferred is settled (completed or failed)
+   * @param {string} key
+   * @returns {boolean}
+   */
+  isSettled(key) {
+    const status = this.status(key)
+    return status === 'completed' || status === 'failed'
+  }
+
+  /**
+   * Get all keys in the registry
+   * @returns {string[]}
+   */
+  keys() {
+    return Array.from(this._entries.keys())
+  }
+
+  /**
+   * Get all entries with their status
+   * @returns {Array<{key: string, status: DeferredStatus, timestamp: number}>}
+   */
+  entries() {
+    return Array.from(this._entries.entries()).map(([key, entry]) => ({
+      key,
+      status: entry.status,
+      timestamp: entry.timestamp
+    }))
+  }
+
+  /**
+   * Clear a specific entry (for cleanup/retry)
+   * @param {string} key
+   * @returns {boolean} True if cleared
+   */
+  clear(key) {
+    return this._entries.delete(key)
+  }
+
+  /**
+   * Clear all entries
+   */
+  clearAll() {
+    this._entries.clear()
+  }
+
+  /**
+   * Emit event via kernel (if provided)
+   * @private
+   */
+  _emit(event, data) {
+    if (this._kernel) {
+      this._kernel.emit(event, data)
+    }
+  }
+
+  /**
+   * Set kernel for event emission
+   * @param {object} kernel - QuarKernel instance
+   */
+  setKernel(kernel) {
+    this._kernel = kernel
+  }
+
+  /**
+   * Enable/disable debug mode
+   * @param {boolean} enabled
+   */
+  debug(enabled) {
+    this._debug = enabled
+  }
+}
+
+/**
+ * Factory function
+ * @param {object} options
+ * @returns {DeferredRegistry}
+ */
+export function createDeferredRegistry(options = {}) {
+  return new DeferredRegistry(options)
+}

package/src/deferred/index.js

@@ -0,0 +1,7 @@
+/**
+ * Deferred Module
+ *
+ * Named promise registry for loose async coupling between services and components.
+ */
+
+export { DeferredRegistry, createDeferredRegistry } from './DeferredRegistry.js'

package/src/entity/EntityManager.js

@@ -58,6 +58,7 @@ export class EntityManager {
       // List behavior
       localFilterThreshold = null,  // Items threshold to switch to local filtering (null = use default)
       readOnly = false,             // If true, canCreate/canUpdate/canDelete return false
+      warmup = true,                // If true, cache is preloaded at boot via DeferredRegistry
       // Scope control
       scopeWhitelist = null,        // Array of scopes/modules that can bypass restrictions
       // Relations
@@ -83,6 +84,7 @@ export class EntityManager {
     // List behavior
     this.localFilterThreshold = localFilterThreshold
     this._readOnly = readOnly
+    this._warmup = warmup
 
     // Scope control
     this._scopeWhitelist = scopeWhitelist
@@ -1039,31 +1041,48 @@ export class EntityManager {
   }
 
   /**
-   * Set up signal listeners for parent entity cache invalidation
+   * Set up signal listeners for cache invalidation
    *
-   * When a parent entity is modified, clears the _search cache on cached items
-   * so that next list() will re-resolve with fresh parent data.
+   * Listens for:
+   * - Parent entity invalidation: clears _search cache and invalidates
+   * - Auth changes: invalidates cache on login/logout (user context changed)
    */
   _setupCacheListeners() {
-    // Nothing to do if no parents or no signals
-    if (!this._parents || Object.keys(this._parents).length === 0) return
     if (!this._signals) return
 
-    // Clean up existing listener if any
+    // Clean up existing listeners if any
     if (this._signalCleanup) {
       this._signalCleanup()
       this._signalCleanup = null
     }
 
-    // Get parent entity names
-    const parentEntities = Object.values(this._parents).map(p => p.entity)
+    const cleanups = []
 
-    // Listen for parent cache invalidation
-    this._signalCleanup = this._signals.on('cache:entity:invalidated', ({ entity }) => {
-      if (parentEntities.includes(entity)) {
-        this._clearSearchCache()
-      }
-    })
+    // Listen for parent cache invalidation (if parents defined)
+    if (this._parents && Object.keys(this._parents).length > 0) {
+      const parentEntities = Object.values(this._parents).map(p => p.entity)
+      cleanups.push(
+        this._signals.on('cache:entity:invalidated', ({ entity }) => {
+          if (parentEntities.includes(entity)) {
+            this._clearSearchCache()
+          }
+        })
+      )
+    }
+
+    // Listen for targeted cache invalidation (routed by EventRouter)
+    // EntityManager only listens to its own signal, staying simple.
+    // EventRouter transforms high-level events (auth:impersonate) into targeted signals.
+    cleanups.push(
+      this._signals.on(`cache:entity:invalidate:${this.name}`, () => {
+        this.invalidateCache()
+      })
+    )
+
+    // Combined cleanup function
+    this._signalCleanup = () => {
+      cleanups.forEach(cleanup => cleanup())
+    }
   }
 
   /**
@@ -1178,6 +1197,55 @@ export class EntityManager {
     return true
   }
 
+  /**
+   * Warmup: preload cache via DeferredRegistry for loose async coupling
+   *
+   * Called by Orchestrator.fireWarmups() at boot. Registers the cache loading
+   * in DeferredRegistry so pages can await it before rendering.
+   *
+   * @returns {Promise<boolean>|null} Promise if warmup started, null if disabled/not applicable
+   *
+   * @example
+   * ```js
+   * // At boot (automatic via Kernel)
+   * orchestrator.warmupAll()
+   *
+   * // In component - await cache ready
+   * await deferred.await('entity:books:cache')
+   * const { items } = await booksManager.list()  // Uses local cache
+   * ```
+   */
+  async warmup() {
+    // Skip if warmup disabled or caching not applicable
+    if (!this._warmup) return null
+    if (!this.isCacheEnabled) return null
+
+    const deferred = this._orchestrator?.deferred
+
+    // Wait for auth if app uses authentication (user context affects cache)
+    if (deferred?.has('auth:ready')) {
+      await deferred.await('auth:ready')
+    }
+
+    const key = `entity:${this.name}:cache`
+
+    if (!deferred) {
+      // Fallback: direct cache load without DeferredRegistry
+      return this.ensureCache()
+    }
+
+    // Register in DeferredRegistry for loose coupling
+    return deferred.queue(key, () => this.ensureCache())
+  }
+
+  /**
+   * Check if warmup is enabled for this manager
+   * @returns {boolean}
+   */
+  get warmupEnabled() {
+    return this._warmup && this.isCacheEnabled
+  }
+
   /**
    * Query entities with automatic cache/API decision
    *