qdadm 0.26.3 → 0.28.0

package/src/entity/storage/factory.test.js

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  parseStoragePattern,
+  storageFactory,
+  defaultStorageResolver,
+  createStorageFactory,
+  storageTypes
+} from './factory.js'
+import { IStorage } from './IStorage.js'
+import { ApiStorage } from './ApiStorage.js'
+import { LocalStorage } from './LocalStorage.js'
+import { MemoryStorage } from './MemoryStorage.js'
+import { MockApiStorage } from './MockApiStorage.js'
+
+describe('parseStoragePattern', () => {
+  it('parses api pattern with endpoint', () => {
+    const result = parseStoragePattern('api:/api/bots')
+    expect(result).toEqual({ type: 'api', endpoint: '/api/bots' })
+  })
+
+  it('parses local pattern with key', () => {
+    const result = parseStoragePattern('local:myKey')
+    expect(result).toEqual({ type: 'local', key: 'myKey' })
+  })
+
+  it('parses memory pattern with key', () => {
+    const result = parseStoragePattern('memory:cache')
+    expect(result).toEqual({ type: 'memory', key: 'cache' })
+  })
+
+  it('parses mock pattern with entityName', () => {
+    const result = parseStoragePattern('mock:users')
+    expect(result).toEqual({ type: 'mock', entityName: 'users' })
+  })
+
+  it('parses sdk pattern with endpoint', () => {
+    const result = parseStoragePattern('sdk:users')
+    expect(result).toEqual({ type: 'sdk', endpoint: 'users' })
+  })
+
+  it('treats bare path as api endpoint', () => {
+    const result = parseStoragePattern('/api/tasks')
+    expect(result).toEqual({ type: 'api', endpoint: '/api/tasks' })
+  })
+
+  it('returns null for invalid pattern', () => {
+    const result = parseStoragePattern('invalid')
+    expect(result).toBeNull()
+  })
+})
+
+describe('defaultStorageResolver', () => {
+  it('creates ApiStorage for api type', () => {
+    const storage = defaultStorageResolver({ type: 'api', endpoint: '/api/bots' }, 'bots')
+    expect(storage).toBeInstanceOf(ApiStorage)
+    expect(storage.endpoint).toBe('/api/bots')
+  })
+
+  it('creates LocalStorage for local type', () => {
+    const storage = defaultStorageResolver({ type: 'local', key: 'myKey' }, 'items')
+    expect(storage).toBeInstanceOf(LocalStorage)
+    expect(storage.storageKey).toBe('myKey')
+  })
+
+  it('creates MemoryStorage for memory type', () => {
+    const storage = defaultStorageResolver({ type: 'memory', key: 'cache' }, 'items')
+    expect(storage).toBeInstanceOf(MemoryStorage)
+  })
+
+  it('creates MockApiStorage for mock type', () => {
+    const storage = defaultStorageResolver({ type: 'mock', entityName: 'users' }, 'users')
+    expect(storage).toBeInstanceOf(MockApiStorage)
+  })
+
+  it('throws for unknown type', () => {
+    expect(() => defaultStorageResolver({ type: 'unknown' }, 'items'))
+      .toThrow('Unknown storage type: unknown')
+  })
+})
+
+describe('storageFactory', () => {
+  it('returns IStorage instance directly', () => {
+    const storage = new ApiStorage({ endpoint: '/api/test' })
+    const result = storageFactory(storage, 'test')
+    expect(result).toBe(storage)
+  })
+
+  it('returns duck-typed storage directly', () => {
+    const duckStorage = {
+      list: () => Promise.resolve({ items: [], total: 0 }),
+      get: () => Promise.resolve(null)
+    }
+    const result = storageFactory(duckStorage, 'test')
+    expect(result).toBe(duckStorage)
+  })
+
+  it('parses string pattern and creates storage', () => {
+    const result = storageFactory('api:/api/bots', 'bots')
+    expect(result).toBeInstanceOf(ApiStorage)
+    expect(result.endpoint).toBe('/api/bots')
+  })
+
+  it('handles bare path as api endpoint', () => {
+    const result = storageFactory('/api/tasks', 'tasks')
+    expect(result).toBeInstanceOf(ApiStorage)
+    expect(result.endpoint).toBe('/api/tasks')
+  })
+
+  it('handles config object with type', () => {
+    const result = storageFactory({ type: 'memory', key: 'cache' }, 'items')
+    expect(result).toBeInstanceOf(MemoryStorage)
+  })
+
+  it('handles config object with string storage', () => {
+    const result = storageFactory({ storage: 'api:/api/items' }, 'items')
+    expect(result).toBeInstanceOf(ApiStorage)
+  })
+
+  it('uses custom resolver when provided', () => {
+    const customResolver = vi.fn().mockReturnValue(new MemoryStorage())
+    const result = storageFactory('api:/test', 'test', customResolver)
+    expect(customResolver).toHaveBeenCalledWith(
+      { type: 'api', endpoint: '/test' },
+      'test'
+    )
+    expect(result).toBeInstanceOf(MemoryStorage)
+  })
+
+  it('throws for invalid config', () => {
+    expect(() => storageFactory(123, 'test'))
+      .toThrow('Invalid storage config')
+  })
+
+  it('throws for unparseable string', () => {
+    expect(() => storageFactory('invalid', 'test'))
+      .toThrow('Cannot parse storage pattern')
+  })
+})
+
+describe('createStorageFactory', () => {
+  it('creates factory with bound context', () => {
+    const customResolver = vi.fn().mockReturnValue(new MemoryStorage())
+    const factory = createStorageFactory(customResolver)
+
+    const result = factory('api:/test', 'test')
+
+    expect(customResolver).toHaveBeenCalled()
+    expect(result).toBeInstanceOf(MemoryStorage)
+  })
+})
+
+describe('storageTypes', () => {
+  it('exports all storage type classes', () => {
+    expect(storageTypes.api).toBe(ApiStorage)
+    expect(storageTypes.local).toBe(LocalStorage)
+    expect(storageTypes.memory).toBe(MemoryStorage)
+    expect(storageTypes.mock).toBe(MockApiStorage)
+  })
+})

package/src/entity/storage/index.js

@@ -110,6 +110,19 @@ export function getStorageCapabilities(storage) {
   }
 }
 
+// Base class
+export { IStorage } from './IStorage.js'
+
+// Factory/Resolver
+export {
+  storageFactory,
+  defaultStorageResolver,
+  createStorageFactory,
+  parseStoragePattern,
+  storageTypes
+} from './factory.js'
+
+// Storage adapters
 export { ApiStorage, createApiStorage } from './ApiStorage.js'
 export { LocalStorage, createLocalStorage } from './LocalStorage.js'
 export { MemoryStorage, createMemoryStorage } from './MemoryStorage.js'

package/src/index.js

@@ -35,6 +35,9 @@ export * from './zones/index.js'
 // Hooks
 export * from './hooks/index.js'
 
+// Deferred (async service loading)
+export * from './deferred/index.js'
+
 // Core (extension helpers)
 export * from './core/index.js'
 

package/src/kernel/EventRouter.js

@@ -0,0 +1,264 @@
+/**
+ * EventRouter - Declarative signal routing
+ *
+ * Routes one signal to multiple targets (signals or callbacks).
+ * Configured at Kernel level to keep components simple.
+ *
+ * Usage:
+ * ```js
+ * const router = new EventRouter({
+ *   signals,      // SignalBus instance
+ *   orchestrator, // Orchestrator instance (optional, for callbacks)
+ *   routes: {
+ *     'auth:impersonate': [
+ *       'cache:entity:invalidate:loans',     // string = emit signal
+ *       { signal: 'notify', transform: (p) => ({ msg: p.user }) },  // object = transform
+ *       (payload, ctx) => { ... }            // function = callback
+ *     ]
+ *   }
+ * })
+ * ```
+ */
+
+/**
+ * Detect cycles in route graph using DFS
+ *
+ * @param {object} routes - Route configuration
+ * @returns {string[]|null} - Cycle path if found, null otherwise
+ */
+function detectCycles(routes) {
+  // Build adjacency list (only signal targets, not callbacks)
+  const graph = new Map()
+
+  for (const [source, targets] of Object.entries(routes)) {
+    const signalTargets = []
+    for (const target of targets) {
+      if (typeof target === 'string') {
+        signalTargets.push(target)
+      } else if (target && typeof target === 'object' && target.signal) {
+        signalTargets.push(target.signal)
+      }
+      // Functions don't create edges in the graph
+    }
+    graph.set(source, signalTargets)
+  }
+
+  // DFS cycle detection
+  const visited = new Set()
+  const recursionStack = new Set()
+  const path = []
+
+  function dfs(node) {
+    visited.add(node)
+    recursionStack.add(node)
+    path.push(node)
+
+    const neighbors = graph.get(node) || []
+    for (const neighbor of neighbors) {
+      if (!visited.has(neighbor)) {
+        const cycle = dfs(neighbor)
+        if (cycle) return cycle
+      } else if (recursionStack.has(neighbor)) {
+        // Found cycle - return path from neighbor to current
+        const cycleStart = path.indexOf(neighbor)
+        return [...path.slice(cycleStart), neighbor]
+      }
+    }
+
+    path.pop()
+    recursionStack.delete(node)
+    return null
+  }
+
+  // Check all nodes
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) {
+      const cycle = dfs(node)
+      if (cycle) return cycle
+    }
+  }
+
+  return null
+}
+
+export class EventRouter {
+  /**
+   * @param {object} options
+   * @param {SignalBus} options.signals - SignalBus instance
+   * @param {Orchestrator} [options.orchestrator] - Orchestrator (for callback context)
+   * @param {object} options.routes - Route configuration
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(options = {}) {
+    const { signals, orchestrator = null, routes = {}, debug = false } = options
+
+    if (!signals) {
+      throw new Error('[EventRouter] signals is required')
+    }
+
+    this._signals = signals
+    this._orchestrator = orchestrator
+    this._routes = routes
+    this._debug = debug
+    this._cleanups = []
+
+    // Validate and setup
+    this._validateRoutes()
+    this._setupListeners()
+  }
+
+  /**
+   * Validate routes configuration and check for cycles
+   * @private
+   */
+  _validateRoutes() {
+    // Check for cycles
+    const cycle = detectCycles(this._routes)
+    if (cycle) {
+      throw new Error(
+        `[EventRouter] Cycle detected: ${cycle.join(' -> ')}`
+      )
+    }
+
+    // Validate each route
+    for (const [source, targets] of Object.entries(this._routes)) {
+      if (!Array.isArray(targets)) {
+        throw new Error(
+          `[EventRouter] Route "${source}" must be an array of targets`
+        )
+      }
+
+      for (let i = 0; i < targets.length; i++) {
+        const target = targets[i]
+        const isString = typeof target === 'string'
+        const isFunction = typeof target === 'function'
+        const isObject = target && typeof target === 'object' && target.signal
+
+        if (!isString && !isFunction && !isObject) {
+          throw new Error(
+            `[EventRouter] Invalid target at "${source}"[${i}]: must be string, function, or { signal, transform? }`
+          )
+        }
+      }
+    }
+  }
+
+  /**
+   * Setup signal listeners for all routes
+   * @private
+   */
+  _setupListeners() {
+    for (const [source, targets] of Object.entries(this._routes)) {
+      const cleanup = this._signals.on(source, (payload) => {
+        this._handleRoute(source, payload, targets)
+      })
+      this._cleanups.push(cleanup)
+    }
+
+    if (this._debug) {
+      console.debug(`[EventRouter] Registered ${Object.keys(this._routes).length} routes`)
+    }
+  }
+
+  /**
+   * Handle a routed signal
+   * @private
+   */
+  _handleRoute(source, payload, targets) {
+    if (this._debug) {
+      console.debug(`[EventRouter] ${source} -> ${targets.length} targets`)
+    }
+
+    const context = {
+      signals: this._signals,
+      orchestrator: this._orchestrator
+    }
+
+    for (const target of targets) {
+      try {
+        if (typeof target === 'string') {
+          // String: emit signal with same payload
+          this._signals.emit(target, payload)
+          if (this._debug) {
+            console.debug(`[EventRouter]   -> ${target} (forward)`)
+          }
+        } else if (typeof target === 'function') {
+          // Function: call callback
+          target(payload, context)
+          if (this._debug) {
+            console.debug(`[EventRouter]   -> callback()`)
+          }
+        } else if (target && target.signal) {
+          // Object: emit signal with transformed payload
+          const transformedPayload = target.transform
+            ? target.transform(payload)
+            : payload
+          this._signals.emit(target.signal, transformedPayload)
+          if (this._debug) {
+            console.debug(`[EventRouter]   -> ${target.signal} (transform)`)
+          }
+        }
+      } catch (error) {
+        console.error(`[EventRouter] Error handling ${source} -> ${JSON.stringify(target)}:`, error)
+      }
+    }
+  }
+
+  /**
+   * Add a route dynamically
+   *
+   * @param {string} source - Source signal
+   * @param {Array} targets - Target array
+   */
+  addRoute(source, targets) {
+    if (this._routes[source]) {
+      throw new Error(`[EventRouter] Route "${source}" already exists`)
+    }
+
+    // Validate new route doesn't create cycle
+    const testRoutes = { ...this._routes, [source]: targets }
+    const cycle = detectCycles(testRoutes)
+    if (cycle) {
+      throw new Error(`[EventRouter] Adding route would create cycle: ${cycle.join(' -> ')}`)
+    }
+
+    this._routes[source] = targets
+
+    // Setup listener
+    const cleanup = this._signals.on(source, (payload) => {
+      this._handleRoute(source, payload, targets)
+    })
+    this._cleanups.push(cleanup)
+  }
+
+  /**
+   * Get all registered routes
+   * @returns {object}
+   */
+  getRoutes() {
+    return { ...this._routes }
+  }
+
+  /**
+   * Dispose the router, cleaning up all listeners
+   */
+  dispose() {
+    for (const cleanup of this._cleanups) {
+      if (typeof cleanup === 'function') {
+        cleanup()
+      }
+    }
+    this._cleanups = []
+    this._routes = {}
+  }
+}
+
+/**
+ * Factory function for creating EventRouter
+ *
+ * @param {object} options
+ * @returns {EventRouter}
+ */
+export function createEventRouter(options) {
+  return new EventRouter(options)
+}

package/src/kernel/Kernel.js

@@ -52,6 +52,10 @@ import { createZoneRegistry } from '../zones/ZoneRegistry.js'
 import { registerStandardZones } from '../zones/zones.js'
 import { createHookRegistry } from '../hooks/HookRegistry.js'
 import { createSecurityChecker } from '../entity/auth/SecurityChecker.js'
+import { createManagers } from '../entity/factory.js'
+import { defaultStorageResolver } from '../entity/storage/factory.js'
+import { createDeferredRegistry } from '../deferred/DeferredRegistry.js'
+import { createEventRouter } from './EventRouter.js'
 
 export class Kernel {
   /**
@@ -60,7 +64,10 @@ export class Kernel {
    * @param {object} options.modules - Result of import.meta.glob for module init files
    * @param {object} options.modulesOptions - Options for initModules (e.g., { coreNavItems })
    * @param {string[]} options.sectionOrder - Navigation section order
-   * @param {object} options.managers - Entity managers { name: EntityManager }
+   * @param {object} options.managers - Entity managers { name: config } - can be instances, strings, or config objects
+   * @param {object} options.managerRegistry - Registry of manager classes from qdadm-gen { name: ManagerClass }
+   * @param {function} options.storageResolver - Custom storage resolver (config, entityName) => Storage
+   * @param {function} options.managerResolver - Custom manager resolver (config, entityName, context) => Manager
    * @param {object} options.authAdapter - Auth adapter for login/logout (app-level authentication)
    * @param {object} options.entityAuthAdapter - Auth adapter for entity permissions (scope/silo checks)
    * @param {object} options.pages - Page components { login, layout }
@@ -73,6 +80,8 @@ export class Kernel {
    * @param {object} options.primevue - PrimeVue config { plugin, theme, options }
    * @param {object} options.layouts - Layout components { list, form, dashboard, base }
    * @param {object} options.security - Security config { role_hierarchy, role_permissions, entity_permissions }
+   * @param {boolean} options.warmup - Enable warmup at boot (default: true)
+   * @param {object} options.eventRouter - EventRouter config { 'source:signal': ['target:signal', ...] }
    */
   constructor(options) {
     this.options = options
@@ -82,6 +91,8 @@ export class Kernel {
     this.orchestrator = null
     this.zoneRegistry = null
     this.hookRegistry = null
+    this.deferred = null
+    this.eventRouter = null
     this.layoutComponents = null
     this.securityChecker = null
   }
@@ -95,19 +106,57 @@ export class Kernel {
     this._createSignalBus()
     this._createHookRegistry()
     this._createZoneRegistry()
-    // 2. Initialize modules (can use all services, registers routes)
+    this._createDeferredRegistry()
+    // 2. Register auth:ready deferred (if auth configured)
+    this._registerAuthDeferred()
+    // 3. Initialize modules (can use all services, registers routes)
     this._initModules()
-    // 3. Create router (needs routes from modules)
+    // 4. Create router (needs routes from modules)
     this._createRouter()
-    // 4. Create orchestrator and remaining components
+    // 5. Create orchestrator and remaining components
     this._createOrchestrator()
+    // 6. Create EventRouter (needs signals + orchestrator)
+    this._createEventRouter()
     this._setupSecurity()
     this._createLayoutComponents()
     this._createVueApp()
     this._installPlugins()
+    // 6. Fire warmups (fire-and-forget, pages await via DeferredRegistry)
+    this._fireWarmups()
     return this.vueApp
   }
 
+  /**
+   * Register auth:ready deferred if auth is configured
+   * This allows warmup and other services to await authentication.
+   */
+  _registerAuthDeferred() {
+    const { authAdapter } = this.options
+    if (!authAdapter) return
+
+    // Create a promise that resolves on first auth:login
+    this.deferred.queue('auth:ready', () => {
+      return new Promise(resolve => {
+        this.signals.once('auth:login', ({ user }) => {
+          resolve(user)
+        })
+      })
+    })
+  }
+
+  /**
+   * Fire entity cache warmups
+   * Fire-and-forget: pages that need cache will await via DeferredRegistry.
+   * Controlled by options.warmup (default: true).
+   */
+  _fireWarmups() {
+    const warmup = this.options.warmup ?? true
+    if (!warmup) return
+
+    // Fire-and-forget: each manager awaits its dependencies (auth:ready, etc.)
+    this.orchestrator.fireWarmups()
+  }
+
   /**
    * Initialize modules from glob import
    * Passes services to modules for zone/signal/hook registration
@@ -121,7 +170,8 @@ export class Kernel {
         ...this.options.modulesOptions,
         zones: this.zoneRegistry,
         signals: this.signals,
-        hooks: this.hookRegistry
+        hooks: this.hookRegistry,
+        deferred: this.deferred
       })
     }
   }
@@ -215,12 +265,28 @@ export class Kernel {
    * Create orchestrator with managers and signal bus
    * Injects entityAuthAdapter and hookRegistry into all managers for permission checks
    * and lifecycle hook support.
+   *
+   * Uses createManagers() to resolve manager configs through the factory pattern:
+   * - String patterns ('api:/api/bots') → creates storage + manager
+   * - Config objects ({ storage: '...', label: '...' }) → resolved
+   * - Manager instances → passed through directly
    */
   _createOrchestrator() {
+    // Build factory context with resolvers and registry
+    const factoryContext = {
+      storageResolver: this.options.storageResolver || defaultStorageResolver,
+      managerResolver: this.options.managerResolver,
+      managerRegistry: this.options.managerRegistry || {}
+    }
+
+    // Resolve all managers through factory
+    const managers = createManagers(this.options.managers || {}, factoryContext)
+
     this.orchestrator = new Orchestrator({
-      managers: this.options.managers || {},
+      managers,
       signals: this.signals,
       hooks: this.hookRegistry,
+      deferred: this.deferred,
       entityAuthAdapter: this.options.entityAuthAdapter || null
     })
   }
@@ -273,6 +339,35 @@ export class Kernel {
     registerStandardZones(this.zoneRegistry)
   }
 
+  /**
+   * Create deferred registry for async service loading
+   * Enables loose coupling between services and components via named promises.
+   */
+  _createDeferredRegistry() {
+    const debug = this.options.debug ?? false
+    this.deferred = createDeferredRegistry({
+      kernel: this.signals?.getKernel(),
+      debug
+    })
+  }
+
+  /**
+   * Create EventRouter for declarative signal routing
+   * Transforms high-level events into targeted signals.
+   */
+  _createEventRouter() {
+    const { eventRouter: routes } = this.options
+    if (!routes || Object.keys(routes).length === 0) return
+
+    const debug = this.options.debug ?? false
+    this.eventRouter = createEventRouter({
+      signals: this.signals,
+      orchestrator: this.orchestrator,
+      routes,
+      debug
+    })
+  }
+
   /**
    * Create layout components map for useLayoutResolver
    * Maps layout types to their Vue components.
@@ -302,7 +397,7 @@ export class Kernel {
    */
   _installPlugins() {
     const app = this.vueApp
-    const { managers, authAdapter, features, primevue } = this.options
+    const { authAdapter, features, primevue } = this.options
 
     // Pinia
     app.use(createPinia())
@@ -346,13 +441,17 @@ export class Kernel {
     // Hook registry injection
     app.provide('qdadmHooks', this.hookRegistry)
 
+    // Deferred registry injection
+    app.provide('qdadmDeferred', this.deferred)
+
     // Layout components injection for useLayoutResolver
     app.provide('qdadmLayoutComponents', this.layoutComponents)
 
     // qdadm plugin
+    // Note: Don't pass managers here - orchestrator already has resolved managers
+    // from createManagers(). Passing raw configs would overwrite them.
     app.use(createQdadm({
       orchestrator: this.orchestrator,
-      managers,
       authAdapter,
       router: this.router,
       toast: app.config.globalProperties.$toast,
@@ -423,6 +522,22 @@ export class Kernel {
     return this.hookRegistry
   }
 
+  /**
+   * Get the DeferredRegistry instance
+   * @returns {import('../deferred/DeferredRegistry.js').DeferredRegistry}
+   */
+  getDeferredRegistry() {
+    return this.deferred
+  }
+
+  /**
+   * Get the EventRouter instance
+   * @returns {import('./EventRouter.js').EventRouter|null}
+   */
+  getEventRouter() {
+    return this.eventRouter
+  }
+
   /**
    * Get the layout components map
    * @returns {object} Layout components by type

package/src/kernel/index.js

@@ -12,3 +12,7 @@ export {
   SIGNAL_ACTIONS,
   buildSignal,
 } from './SignalBus.js'
+export {
+  EventRouter,
+  createEventRouter,
+} from './EventRouter.js'