qdadm 0.26.3 → 0.28.0

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
    *

package/src/entity/factory.js

@@ -0,0 +1,155 @@
+/**
+ * Manager Factory/Resolver Pattern
+ *
+ * Enables declarative manager configuration with auto-resolution.
+ * Works with storageFactory for complete auto-wiring.
+ *
+ * Usage:
+ * ```js
+ * // String pattern → factory creates manager with storage
+ * managerFactory('api:/api/bots', 'bots', context)  // → EntityManager + ApiStorage
+ *
+ * // Config object → factory normalizes, resolver creates
+ * managerFactory({ storage: 'api:/api/bots', label: 'Bot' }, 'bots', context)
+ *
+ * // Manager instance → returned directly
+ * managerFactory(myManagerInstance, 'bots', context)  // → myManagerInstance
+ * ```
+ */
+
+import { EntityManager } from './EntityManager.js'
+import { storageFactory } from './storage/factory.js'
+
+/**
+ * Default manager resolver - creates manager instance from config
+ *
+ * Override this via Kernel config for custom manager classes.
+ *
+ * @param {object} config - Normalized manager config with resolved storage
+ * @param {string} entityName - Entity name
+ * @param {object} context - Context with managerRegistry
+ * @returns {EntityManager} Manager instance
+ */
+export function defaultManagerResolver(config, entityName, context = {}) {
+  const { managerRegistry = {} } = context
+
+  // Look up registered manager class (e.g., from qdadm-gen)
+  const ManagerClass = managerRegistry[entityName] || EntityManager
+
+  // Ensure name is set
+  const managerConfig = {
+    name: entityName,
+    ...config
+  }
+
+  return new ManagerClass(managerConfig)
+}
+
+/**
+ * Manager factory - normalizes input and delegates to resolver
+ *
+ * Handles:
+ * - EntityManager instance → return directly
+ * - String pattern 'type:endpoint' → create storage, then manager
+ * - Config object → resolve storage, then manager
+ *
+ * @param {EntityManager | string | object} config - Manager config
+ * @param {string} entityName - Entity name
+ * @param {object} context - Context with storageFactory, storageResolver, managerResolver, managerRegistry
+ * @returns {EntityManager} Manager instance
+ *
+ * @example
+ * // Instance passthrough
+ * managerFactory(myManager, 'bots', ctx)  // → myManager
+ *
+ * // String pattern (shorthand for storage)
+ * managerFactory('api:/api/bots', 'bots', ctx)  // → EntityManager + ApiStorage
+ *
+ * // Config object
+ * managerFactory({
+ *   storage: 'api:/api/bots',
+ *   label: 'Bot',
+ *   fields: { name: { type: 'text' } }
+ * }, 'bots', ctx)
+ */
+export function managerFactory(config, entityName, context = {}) {
+  const {
+    storageResolver,
+    managerResolver = defaultManagerResolver
+  } = context
+
+  // Already a Manager instance → return directly
+  if (config instanceof EntityManager) {
+    return config
+  }
+
+  // Also check for duck-typed manager (has storage property or list/get methods)
+  if (config && typeof config === 'object' && config.storage && typeof config.list === 'function') {
+    return config
+  }
+
+  // String pattern → treat as storage config, create default manager
+  if (typeof config === 'string') {
+    const storage = storageFactory(config, entityName, storageResolver)
+    return managerResolver({ storage }, entityName, context)
+  }
+
+  // Config object → resolve storage first, then manager
+  if (config && typeof config === 'object') {
+    let resolvedConfig = { ...config }
+
+    // Resolve storage if provided as string/config
+    if (config.storage && !(config.storage instanceof Object && typeof config.storage.list === 'function')) {
+      resolvedConfig.storage = storageFactory(config.storage, entityName, storageResolver)
+    }
+
+    return managerResolver(resolvedConfig, entityName, context)
+  }
+
+  throw new Error(`Invalid manager config for "${entityName}": ${typeof config}. Expected string, object, or Manager instance.`)
+}
+
+/**
+ * Create a custom manager factory with context
+ *
+ * @param {object} context - Context with storageResolver, managerResolver, managerRegistry
+ * @returns {function} Manager factory with bound context
+ *
+ * @example
+ * const myFactory = createManagerFactory({
+ *   managerRegistry: { bots: BotManager },
+ *   managerResolver: (config, name, ctx) => {
+ *     // Custom logic
+ *     return defaultManagerResolver(config, name, ctx)
+ *   }
+ * })
+ *
+ * const botsManager = myFactory('api:/api/bots', 'bots')
+ */
+export function createManagerFactory(context) {
+  return (config, entityName) => managerFactory(config, entityName, context)
+}
+
+/**
+ * Create all managers from a config object
+ *
+ * @param {object} managersConfig - { entityName: config, ... }
+ * @param {object} context - Factory context
+ * @returns {object} { entityName: managerInstance, ... }
+ *
+ * @example
+ * const managers = createManagers({
+ *   bots: 'api:/api/bots',
+ *   tasks: { storage: 'api:/api/tasks', label: 'Task' },
+ *   settings: new SettingsManager({...})
+ * }, { managerRegistry })
+ */
+export function createManagers(managersConfig, context = {}) {
+  const managers = {}
+
+  for (const [entityName, config] of Object.entries(managersConfig)) {
+    managers[entityName] = managerFactory(config, entityName, context)
+  }
+
+  return managers
+}