qdadm 0.30.0 → 0.32.0

package/src/entity/EntityManager.js

@@ -119,6 +119,19 @@ export class EntityManager {
 
     // Cleanup function for signal listeners
     this._signalCleanup = null
+
+    // Operation stats tracking (for debug panel)
+    this._stats = {
+      list: 0,         // Total list() calls
+      get: 0,          // Total get() calls
+      create: 0,       // Total create() calls
+      update: 0,       // Total update() calls (includes patch)
+      delete: 0,       // Total delete() calls
+      cacheHits: 0,    // list() served from local cache
+      cacheMisses: 0,  // list() fetched from API
+      maxItemsSeen: 0, // Max items returned in a single list()
+      maxTotal: 0      // Max total count reported by API
+    }
   }
 
   // ============ SIGNALS ============
@@ -166,20 +179,15 @@ export class EntityManager {
   /**
    * Invoke a lifecycle hook for this entity
    *
-   * Invokes both entity-specific hook (e.g., 'books:presave') and
-   * generic hook (e.g., 'entity:presave'). Entity-specific hooks run first.
+   * Invokes generic hook (e.g., 'entity:presave') with entity name in context.
+   * Handlers can filter by context.entity if needed.
    *
    * @param {string} hookName - Hook name without entity prefix (e.g., 'presave')
-   * @param {object} context - Hook context passed to handlers
+   * @param {object} context - Hook context passed to handlers (includes entity name)
    * @private
    */
   async _invokeHook(hookName, context) {
     if (!this._hooks) return
-
-    // Invoke entity-specific hook first (e.g., 'books:presave')
-    await this._hooks.invoke(`${this.name}:${hookName}`, context)
-
-    // Invoke generic hook (e.g., 'entity:presave')
     await this._hooks.invoke(`entity:${hookName}`, context)
   }
 
@@ -688,35 +696,67 @@ export class EntityManager {
       throw new Error(`[EntityManager:${this.name}] list() not implemented`)
     }
 
-    // Extract cacheSafe flag (for ownership/scope filters that are session-bound)
-    const { cacheSafe = false, ...queryParams } = params
+    // Extract internal flag and cacheSafe flag
+    const { _internal = false, cacheSafe = false, ...queryParams } = params
+
+    // Only count stats for non-internal operations
+    if (!_internal) {
+      this._stats.list++
+    }
 
     const hasFilters = queryParams.search || Object.keys(queryParams.filters || {}).length > 0
     const canUseCache = !hasFilters || cacheSafe
 
     // 1. Cache valid + cacheable → use cache with local filtering
     if (this._cache.valid && canUseCache) {
+      if (!_internal) this._stats.cacheHits++
       console.log('[cache] Using local cache for entity:', this.name)
       const filtered = this._filterLocally(this._cache.items, queryParams)
+      // Update max stats
+      if (filtered.items.length > this._stats.maxItemsSeen) {
+        this._stats.maxItemsSeen = filtered.items.length
+      }
+      if (filtered.total > this._stats.maxTotal) {
+        this._stats.maxTotal = filtered.total
+      }
       return { ...filtered, fromCache: true }
     }
 
+    if (!_internal) this._stats.cacheMisses++
+
     // 2. Fetch from API (storage normalizes response to { items, total })
     const response = await this.storage.list(queryParams)
     const items = response.items || []
     const total = response.total ?? items.length
 
+    // Update max stats
+    if (items.length > this._stats.maxItemsSeen) {
+      this._stats.maxItemsSeen = items.length
+    }
+    if (total > this._stats.maxTotal) {
+      this._stats.maxTotal = total
+    }
+
     // 3. Fill cache opportunistically if:
     //    - canUseCache (no filters or cacheSafe filters)
     //    - isCacheEnabled (threshold > 0 and storage supports total)
     //    - total <= threshold (all items fit in cache for complete local filtering)
+    //    - items.length >= total (we actually received all items)
     if (canUseCache && this.isCacheEnabled && total <= this.effectiveThreshold) {
-      this._cache.items = items  // Store all items (no slicing - total fits threshold)
-      this._cache.total = total
-      this._cache.valid = true
-      this._cache.loadedAt = Date.now()
-      // Resolve parent fields for search (book.title, user.username, etc.)
-      await this._resolveSearchFields(items)
+      // Only cache if we received ALL items (not a partial page)
+      if (items.length >= total) {
+        this._cache.items = items
+        this._cache.total = total
+        this._cache.valid = true
+        this._cache.loadedAt = Date.now()
+        // Resolve parent fields for search (book.title, user.username, etc.)
+        await this._resolveSearchFields(items)
+      }
+      // If we got partial results but total fits threshold, load all items for cache
+      else if (!this._cacheLoading) {
+        // Fire-and-forget: load full cache in background
+        this._loadCacheInBackground()
+      }
     }
 
     return { items, total, fromCache: false }
@@ -724,10 +764,28 @@ export class EntityManager {
 
   /**
    * Get a single entity by ID
+   *
+   * If cache is valid and complete (not overflow), serves from cache.
+   * Otherwise fetches from storage.
+   *
    * @param {string|number} id
    * @returns {Promise<object>}
    */
   async get(id) {
+    this._stats.get++
+
+    // Try cache first if valid and complete
+    if (this._cache.valid && !this.overflow) {
+      const idStr = String(id)
+      const cached = this._cache.items.find(item => String(item[this.idField]) === idStr)
+      if (cached) {
+        this._stats.cacheHits++
+        return { ...cached }  // Return copy to avoid mutation
+      }
+    }
+
+    // Fallback to storage
+    this._stats.cacheMisses++
     if (this.storage) {
       return this.storage.get(id)
     }
@@ -736,15 +794,38 @@ export class EntityManager {
 
   /**
    * Get multiple entities by IDs (batch fetch)
+   *
+   * If cache is valid and complete, serves from cache.
+   * Otherwise fetches from storage (or parallel get() calls).
+   *
    * @param {Array<string|number>} ids
    * @returns {Promise<Array<object>>}
    */
   async getMany(ids) {
     if (!ids || ids.length === 0) return []
+
+    // Try cache first if valid and complete
+    if (this._cache.valid && !this.overflow) {
+      const idStrs = new Set(ids.map(String))
+      const cached = this._cache.items
+        .filter(item => idStrs.has(String(item[this.idField])))
+        .map(item => ({ ...item }))  // Return copies
+
+      // If we found all items in cache
+      if (cached.length === ids.length) {
+        this._stats.cacheHits += ids.length
+        return cached
+      }
+      // Partial cache hit - fall through to storage
+    }
+
+    this._stats.cacheMisses += ids.length
+
     if (this.storage?.getMany) {
       return this.storage.getMany(ids)
     }
-    // Fallback: parallel get calls
+    // Fallback: parallel get calls (get() handles its own stats)
+    this._stats.cacheMisses -= ids.length  // Avoid double counting
     return Promise.all(ids.map(id => this.get(id).catch(() => null)))
       .then(results => results.filter(Boolean))
   }
@@ -760,6 +841,7 @@ export class EntityManager {
    * @returns {Promise<object>} - The created entity
    */
   async create(data) {
+    this._stats.create++
     if (this.storage) {
       // Invoke presave hooks (can modify data or throw to abort)
       const presaveContext = this._buildPresaveContext(data, true)
@@ -795,6 +877,7 @@ export class EntityManager {
    * @returns {Promise<object>}
    */
   async update(id, data) {
+    this._stats.update++
     if (this.storage) {
       // Invoke presave hooks (can modify data or throw to abort)
       const presaveContext = this._buildPresaveContext(data, false, id)
@@ -830,6 +913,7 @@ export class EntityManager {
    * @returns {Promise<object>}
    */
   async patch(id, data) {
+    this._stats.update++  // patch counts as update
     if (this.storage) {
       // Invoke presave hooks (can modify data or throw to abort)
       const presaveContext = this._buildPresaveContext(data, false, id)
@@ -863,6 +947,7 @@ export class EntityManager {
    * @returns {Promise<void>}
    */
   async delete(id) {
+    this._stats.delete++
     if (this.storage) {
       // Invoke predelete hooks (can throw to abort, e.g., for cascade checks)
       const predeleteContext = this._buildPredeleteContext(id)
@@ -1172,13 +1257,25 @@ export class EntityManager {
     return result
   }
 
+  /**
+   * Internal: load all items into cache in background (fire-and-forget)
+   * Called when a partial list() response indicates caching is possible.
+   */
+  _loadCacheInBackground() {
+    this._cacheLoading = this._loadCache()
+    this._cacheLoading
+      .catch(err => console.error(`[EntityManager:${this.name}] Background cache load failed:`, err))
+      .finally(() => { this._cacheLoading = null })
+  }
+
   /**
    * Internal: load all items into cache
    * @returns {Promise<boolean>} - true if cached, false if too many items
    */
   async _loadCache() {
     // First, check total count with minimal request
-    const probe = await this.list({ page_size: 1 })
+    // Use _internal to skip stats counting
+    const probe = await this.list({ page_size: 1, _internal: true })
 
     if (probe.total > this.effectiveThreshold) {
       // Too many items, don't cache
@@ -1186,8 +1283,8 @@ export class EntityManager {
       return false
     }
 
-    // Load all items
-    const result = await this.list({ page_size: probe.total || this.effectiveThreshold })
+    // Load all items (internal operation, skip stats)
+    const result = await this.list({ page_size: probe.total || this.effectiveThreshold, _internal: true })
     this._cache.items = result.items || []
     this._cache.total = result.total
     this._cache.loadedAt = Date.now()
@@ -1443,6 +1540,31 @@ export class EntityManager {
     }
   }
 
+  /**
+   * Get operation stats (for debug panel)
+   * @returns {object}
+   */
+  getStats() {
+    return { ...this._stats }
+  }
+
+  /**
+   * Reset operation stats
+   */
+  resetStats() {
+    this._stats = {
+      list: 0,
+      get: 0,
+      create: 0,
+      update: 0,
+      delete: 0,
+      cacheHits: 0,
+      cacheMisses: 0,
+      maxItemsSeen: 0,
+      maxTotal: 0
+    }
+  }
+
   // ============ RELATIONS ============
 
   /**

package/src/entity/auth/CompositeAuthAdapter.js

@@ -0,0 +1,212 @@
+/**
+ * CompositeAuthAdapter - Routes to sub-adapters based on entity patterns
+ *
+ * Enables multi-source authentication where different entities may use
+ * different auth backends (internal JWT, external API keys, OAuth, etc.)
+ *
+ * Pattern matching:
+ * - Exact match: 'products' matches only 'products'
+ * - Prefix glob: 'external-*' matches 'external-products', 'external-orders'
+ * - Suffix glob: '*-readonly' matches 'products-readonly'
+ *
+ * @example
+ * ```js
+ * const composite = new CompositeAuthAdapter({
+ *   default: internalAuthAdapter,  // JWT for most entities
+ *   mapping: {
+ *     'products': apiKeyAdapter,    // API key for products
+ *     'external-*': externalAuth,   // OAuth for external-* entities
+ *     'readonly-*': readonlyAuth    // Read-only adapter
+ *   }
+ * })
+ *
+ * composite.canPerform('books', 'read')     // → uses default (internal)
+ * composite.canPerform('products', 'read')  // → uses apiKeyAdapter
+ * composite.canPerform('external-orders', 'read')  // → uses externalAuth
+ * ```
+ */
+
+import { AuthAdapter } from './AuthAdapter.js'
+import { authFactory } from './factory.js'
+
+export class CompositeAuthAdapter extends AuthAdapter {
+  /**
+   * @param {object} config - Composite auth configuration
+   * @param {AuthAdapter|string|object} config.default - Default adapter (required)
+   * @param {Object<string, AuthAdapter|string|object>} [config.mapping={}] - Entity pattern to adapter mapping
+   * @param {object} [context={}] - Factory context with authTypes
+   */
+  constructor(config, context = {}) {
+    super()
+
+    const { default: defaultConfig, mapping = {} } = config
+
+    if (!defaultConfig) {
+      throw new Error('[CompositeAuthAdapter] "default" adapter is required')
+    }
+
+    // Resolve default adapter via factory
+    this._default = authFactory(defaultConfig, context)
+
+    // Resolve mapped adapters
+    this._exactMatches = new Map()
+    this._patterns = []
+
+    for (const [pattern, adapterConfig] of Object.entries(mapping)) {
+      const adapter = authFactory(adapterConfig, context)
+
+      if (pattern.includes('*')) {
+        // Glob pattern: convert to regex
+        const regexPattern = pattern
+          .replace(/[.+?^${}()|[\]\\]/g, '\\$&')  // Escape regex special chars
+          .replace(/\*/g, '.*')  // * → .*
+        const regex = new RegExp(`^${regexPattern}$`)
+        this._patterns.push({ pattern, regex, adapter })
+      } else {
+        // Exact match
+        this._exactMatches.set(pattern, adapter)
+      }
+    }
+  }
+
+  /**
+   * Get the adapter for a specific entity
+   *
+   * Resolution order:
+   * 1. Exact match in mapping
+   * 2. First matching glob pattern
+   * 3. Default adapter
+   *
+   * @param {string} entity - Entity name
+   * @returns {AuthAdapter}
+   */
+  _getAdapter(entity) {
+    // 1. Exact match
+    if (this._exactMatches.has(entity)) {
+      return this._exactMatches.get(entity)
+    }
+
+    // 2. Pattern match (first wins)
+    for (const { regex, adapter } of this._patterns) {
+      if (regex.test(entity)) {
+        return adapter
+      }
+    }
+
+    // 3. Default
+    return this._default
+  }
+
+  /**
+   * Check if user can perform action on entity type (scope check)
+   * Delegates to the appropriate adapter based on entity name
+   *
+   * @param {string} entity - Entity name
+   * @param {string} action - Action: read, create, update, delete, list
+   * @returns {boolean}
+   */
+  canPerform(entity, action) {
+    return this._getAdapter(entity).canPerform(entity, action)
+  }
+
+  /**
+   * Check if user can access specific record (silo check)
+   * Delegates to the appropriate adapter based on entity name
+   *
+   * @param {string} entity - Entity name
+   * @param {object} record - The record to check
+   * @returns {boolean}
+   */
+  canAccessRecord(entity, record) {
+    return this._getAdapter(entity).canAccessRecord(entity, record)
+  }
+
+  /**
+   * Get current user from the default adapter
+   * The "user" concept comes from the primary auth source
+   *
+   * @returns {object|null}
+   */
+  getCurrentUser() {
+    return this._default.getCurrentUser()
+  }
+
+  /**
+   * Check if user is granted an attribute (role or permission)
+   * Delegates to default adapter for global permissions
+   *
+   * @param {string} attribute - Role or permission to check
+   * @param {object} [subject] - Optional subject for context
+   * @returns {boolean}
+   */
+  isGranted(attribute, subject = null) {
+    // For entity-specific permissions (entity:action), route to appropriate adapter
+    if (attribute.includes(':') && !attribute.startsWith('ROLE_')) {
+      const [entity] = attribute.split(':')
+      const adapter = this._getAdapter(entity)
+      if (adapter.isGranted) {
+        return adapter.isGranted(attribute, subject)
+      }
+    }
+
+    // Global permissions use default adapter
+    if (this._default.isGranted) {
+      return this._default.isGranted(attribute, subject)
+    }
+
+    // Fallback for adapters without isGranted
+    return true
+  }
+
+  /**
+   * Get the default adapter
+   * @returns {AuthAdapter}
+   */
+  get defaultAdapter() {
+    return this._default
+  }
+
+  /**
+   * Get adapter info for debugging
+   * @returns {object}
+   */
+  getAdapterInfo() {
+    const info = {
+      default: this._getAdapterName(this._default),
+      exactMatches: {},
+      patterns: []
+    }
+
+    for (const [entity, adapter] of this._exactMatches) {
+      info.exactMatches[entity] = this._getAdapterName(adapter)
+    }
+
+    for (const { pattern, adapter } of this._patterns) {
+      info.patterns.push({
+        pattern,
+        adapter: this._getAdapterName(adapter)
+      })
+    }
+
+    return info
+  }
+
+  /**
+   * Get adapter name for debugging
+   * @private
+   */
+  _getAdapterName(adapter) {
+    return adapter.constructor?.name || 'Unknown'
+  }
+}
+
+/**
+ * Factory function to create CompositeAuthAdapter
+ *
+ * @param {object} config - { default, mapping }
+ * @param {object} [context] - Factory context
+ * @returns {CompositeAuthAdapter}
+ */
+export function createCompositeAuthAdapter(config, context = {}) {
+  return new CompositeAuthAdapter(config, context)
+}

package/src/entity/auth/factory.js

@@ -0,0 +1,207 @@
+/**
+ * Auth Factory/Resolver Pattern
+ *
+ * Enables declarative auth adapter configuration with auto-resolution.
+ * Follows the same pattern as storage/factory.js for consistency.
+ *
+ * IMPORTANT: Backward compatible - passing an AuthAdapter instance
+ * works exactly as before (simple passthrough).
+ *
+ * Usage:
+ * ```js
+ * // Instance passthrough (current behavior, unchanged)
+ * authFactory(myAdapter)  // → myAdapter
+ *
+ * // String pattern → factory resolves from registry
+ * authFactory('permissive')  // → PermissiveAuthAdapter
+ * authFactory('jwt:internal')  // → JwtAuthAdapter (if registered)
+ *
+ * // Config object → factory resolves
+ * authFactory({ type: 'jwt', tokenKey: 'auth_token' })
+ *
+ * // Composite config → creates CompositeAuthAdapter
+ * authFactory({
+ *   default: myAdapter,
+ *   mapping: { 'external-*': externalAdapter }
+ * })
+ * ```
+ */
+
+import { AuthAdapter } from './AuthAdapter.js'
+import { PermissiveAuthAdapter } from './PermissiveAdapter.js'
+
+/**
+ * Built-in auth adapter types
+ * Extended via context.authTypes for custom adapters
+ * @type {Record<string, typeof AuthAdapter>}
+ */
+export const authTypes = {
+  permissive: PermissiveAuthAdapter
+}
+
+/**
+ * Parse auth pattern 'type' or 'type:scope'
+ *
+ * @param {string} pattern - Auth pattern (e.g., 'jwt', 'apikey:external')
+ * @returns {{type: string, scope?: string} | null} Parsed config or null
+ *
+ * @example
+ * parseAuthPattern('jwt')            // → { type: 'jwt' }
+ * parseAuthPattern('apikey:external') // → { type: 'apikey', scope: 'external' }
+ */
+export function parseAuthPattern(pattern) {
+  if (typeof pattern !== 'string') return null
+
+  const match = pattern.match(/^(\w+)(?::(.+))?$/)
+  if (match) {
+    const [, type, scope] = match
+    return scope ? { type, scope } : { type }
+  }
+  return null
+}
+
+/**
+ * Default auth resolver - creates adapter instance from config
+ *
+ * @param {object} config - Normalized auth config with `type` property
+ * @param {object} context - Context with authTypes registry
+ * @returns {AuthAdapter} Adapter instance
+ */
+export function defaultAuthResolver(config, context = {}) {
+  const { type, ...rest } = config
+
+  // Merge built-in types with custom types from context
+  const allTypes = { ...authTypes, ...context.authTypes }
+  const AdapterClass = allTypes[type]
+
+  if (!AdapterClass) {
+    throw new Error(
+      `[authFactory] Unknown auth type: "${type}". ` +
+      `Available: ${Object.keys(allTypes).join(', ')}`
+    )
+  }
+
+  return new AdapterClass(rest)
+}
+
+/**
+ * Check if config is a composite auth config
+ * Composite config has 'default' + optional 'mapping'
+ *
+ * @param {any} config
+ * @returns {boolean}
+ */
+function isCompositeConfig(config) {
+  return (
+    config &&
+    typeof config === 'object' &&
+    'default' in config &&
+    !('type' in config)
+  )
+}
+
+/**
+ * Auth factory - normalizes input and resolves to adapter
+ *
+ * Handles:
+ * - AuthAdapter instance → return directly (backward compatible)
+ * - String pattern 'type' → parse and resolve
+ * - Config object with 'type' → resolve via registry
+ * - Config object with 'default' → create CompositeAuthAdapter
+ *
+ * @param {AuthAdapter | string | object} config - Auth config
+ * @param {object} [context={}] - Context with authTypes, authResolver
+ * @returns {AuthAdapter} Adapter instance
+ *
+ * @example
+ * // Instance passthrough (most common, backward compatible)
+ * authFactory(myAdapter)  // → myAdapter
+ *
+ * // String patterns
+ * authFactory('permissive')  // → PermissiveAuthAdapter
+ * authFactory('jwt')  // → JwtAuthAdapter (if registered)
+ *
+ * // Config objects
+ * authFactory({ type: 'jwt', tokenKey: 'token' })
+ *
+ * // Composite (multi-source)
+ * authFactory({
+ *   default: myAdapter,
+ *   mapping: { 'products': apiKeyAdapter }
+ * })
+ */
+export function authFactory(config, context = {}) {
+  const { authResolver = defaultAuthResolver } = context
+
+  // Null/undefined → permissive (safe default)
+  if (config == null) {
+    return new PermissiveAuthAdapter()
+  }
+
+  // Already an AuthAdapter instance → return directly (backward compatible)
+  if (config instanceof AuthAdapter) {
+    return config
+  }
+
+  // Duck-typed adapter (has canPerform method)
+  if (typeof config.canPerform === 'function') {
+    return config
+  }
+
+  // String pattern → parse and resolve
+  if (typeof config === 'string') {
+    const parsed = parseAuthPattern(config)
+    if (!parsed) {
+      throw new Error(`[authFactory] Invalid auth pattern: "${config}"`)
+    }
+    return authResolver(parsed, context)
+  }
+
+  // Config object
+  if (typeof config === 'object') {
+    // Composite config: { default: ..., mapping: { ... } }
+    // Handled separately to avoid circular dependency
+    // The CompositeAuthAdapter is resolved via authTypes registry
+    if (isCompositeConfig(config)) {
+      const CompositeClass = context.authTypes?.composite || context.CompositeAuthAdapter
+      if (!CompositeClass) {
+        throw new Error(
+          '[authFactory] Composite config requires CompositeAuthAdapter. ' +
+          'Pass it via context.CompositeAuthAdapter or register as context.authTypes.composite'
+        )
+      }
+      return new CompositeClass(config, context)
+    }
+
+    // Simple config with type: { type: 'jwt', ... }
+    if (config.type) {
+      return authResolver(config, context)
+    }
+
+    throw new Error(
+      '[authFactory] Config object requires either "type" or "default" property'
+    )
+  }
+
+  throw new Error(
+    `[authFactory] Invalid auth config: ${typeof config}. ` +
+    'Expected AuthAdapter instance, string, or config object.'
+  )
+}
+
+/**
+ * Create a custom auth factory with bound context
+ *
+ * @param {object} context - Context with authTypes, authResolver
+ * @returns {function} Auth factory with bound context
+ *
+ * @example
+ * const myAuthFactory = createAuthFactory({
+ *   authTypes: { jwt: JwtAuthAdapter, apikey: ApiKeyAuthAdapter }
+ * })
+ *
+ * const adapter = myAuthFactory('jwt')
+ */
+export function createAuthFactory(context) {
+  return (config) => authFactory(config, context)
+}