qdadm 0.30.0 → 0.32.0

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

@@ -0,0 +1,257 @@
+/**
+ * Tests for auth factory and CompositeAuthAdapter
+ */
+import { describe, it, expect } from 'vitest'
+import { AuthAdapter } from './AuthAdapter.js'
+import { PermissiveAuthAdapter } from './PermissiveAdapter.js'
+import { CompositeAuthAdapter } from './CompositeAuthAdapter.js'
+import { authFactory, parseAuthPattern, authTypes } from './factory.js'
+
+// Test adapter for custom types
+class TestAuthAdapter extends AuthAdapter {
+  constructor(options = {}) {
+    super()
+    this.options = options
+  }
+  canPerform() { return true }
+  canAccessRecord() { return true }
+  getCurrentUser() { return { id: 'test' } }
+}
+
+// Adapter that tracks which entity was checked
+class TrackingAdapter extends AuthAdapter {
+  constructor(name) {
+    super()
+    this.name = name
+    this.checkedEntities = []
+  }
+  canPerform(entity, action) {
+    this.checkedEntities.push({ entity, action })
+    return true
+  }
+  canAccessRecord() { return true }
+  getCurrentUser() { return { name: this.name } }
+}
+
+describe('parseAuthPattern', () => {
+  it('parses simple type', () => {
+    expect(parseAuthPattern('jwt')).toEqual({ type: 'jwt' })
+    expect(parseAuthPattern('permissive')).toEqual({ type: 'permissive' })
+  })
+
+  it('parses type with scope', () => {
+    expect(parseAuthPattern('jwt:internal')).toEqual({ type: 'jwt', scope: 'internal' })
+    expect(parseAuthPattern('apikey:external')).toEqual({ type: 'apikey', scope: 'external' })
+  })
+
+  it('returns null for invalid input', () => {
+    expect(parseAuthPattern(null)).toBeNull()
+    expect(parseAuthPattern(123)).toBeNull()
+    expect(parseAuthPattern('')).toBeNull()
+  })
+})
+
+describe('authFactory', () => {
+  describe('instance passthrough', () => {
+    it('returns AuthAdapter instance as-is', () => {
+      const adapter = new PermissiveAuthAdapter()
+      const result = authFactory(adapter)
+      expect(result).toBe(adapter)
+    })
+
+    it('returns duck-typed adapter as-is', () => {
+      const duckAdapter = {
+        canPerform: () => true,
+        canAccessRecord: () => true,
+        getCurrentUser: () => null
+      }
+      const result = authFactory(duckAdapter)
+      expect(result).toBe(duckAdapter)
+    })
+  })
+
+  describe('null/undefined', () => {
+    it('returns PermissiveAuthAdapter for null', () => {
+      const result = authFactory(null)
+      expect(result).toBeInstanceOf(PermissiveAuthAdapter)
+    })
+
+    it('returns PermissiveAuthAdapter for undefined', () => {
+      const result = authFactory(undefined)
+      expect(result).toBeInstanceOf(PermissiveAuthAdapter)
+    })
+  })
+
+  describe('string patterns', () => {
+    it('resolves built-in types', () => {
+      const result = authFactory('permissive')
+      expect(result).toBeInstanceOf(PermissiveAuthAdapter)
+    })
+
+    it('resolves custom types from context', () => {
+      const result = authFactory('test', {
+        authTypes: { test: TestAuthAdapter }
+      })
+      expect(result).toBeInstanceOf(TestAuthAdapter)
+    })
+
+    it('throws for unknown type', () => {
+      expect(() => authFactory('unknown')).toThrow(/Unknown auth type/)
+    })
+  })
+
+  describe('config objects', () => {
+    it('resolves config with type', () => {
+      const result = authFactory(
+        { type: 'test', foo: 'bar' },
+        { authTypes: { test: TestAuthAdapter } }
+      )
+      expect(result).toBeInstanceOf(TestAuthAdapter)
+      expect(result.options.foo).toBe('bar')
+    })
+
+    it('throws for config without type or default', () => {
+      expect(() => authFactory({ foo: 'bar' })).toThrow(/requires either "type" or "default"/)
+    })
+  })
+
+  describe('composite config', () => {
+    it('creates CompositeAuthAdapter from config', () => {
+      const defaultAdapter = new PermissiveAuthAdapter()
+      const result = authFactory(
+        { default: defaultAdapter },
+        { CompositeAuthAdapter }
+      )
+      expect(result).toBeInstanceOf(CompositeAuthAdapter)
+    })
+
+    it('throws without CompositeAuthAdapter in context', () => {
+      const defaultAdapter = new PermissiveAuthAdapter()
+      expect(() => authFactory({ default: defaultAdapter })).toThrow(/CompositeAuthAdapter/)
+    })
+  })
+})
+
+describe('CompositeAuthAdapter', () => {
+  describe('routing', () => {
+    it('uses default adapter for unmatched entities', () => {
+      const defaultAdapter = new TrackingAdapter('default')
+      const composite = new CompositeAuthAdapter({ default: defaultAdapter })
+
+      composite.canPerform('books', 'read')
+      composite.canPerform('users', 'create')
+
+      expect(defaultAdapter.checkedEntities).toEqual([
+        { entity: 'books', action: 'read' },
+        { entity: 'users', action: 'create' }
+      ])
+    })
+
+    it('routes exact matches to mapped adapter', () => {
+      const defaultAdapter = new TrackingAdapter('default')
+      const productsAdapter = new TrackingAdapter('products')
+
+      const composite = new CompositeAuthAdapter({
+        default: defaultAdapter,
+        mapping: { products: productsAdapter }
+      })
+
+      composite.canPerform('books', 'read')
+      composite.canPerform('products', 'read')
+
+      expect(defaultAdapter.checkedEntities).toHaveLength(1)
+      expect(defaultAdapter.checkedEntities[0].entity).toBe('books')
+
+      expect(productsAdapter.checkedEntities).toHaveLength(1)
+      expect(productsAdapter.checkedEntities[0].entity).toBe('products')
+    })
+
+    it('routes glob patterns to mapped adapter', () => {
+      const defaultAdapter = new TrackingAdapter('default')
+      const externalAdapter = new TrackingAdapter('external')
+
+      const composite = new CompositeAuthAdapter({
+        default: defaultAdapter,
+        mapping: { 'external-*': externalAdapter }
+      })
+
+      composite.canPerform('books', 'read')
+      composite.canPerform('external-products', 'read')
+      composite.canPerform('external-orders', 'list')
+
+      expect(defaultAdapter.checkedEntities).toHaveLength(1)
+      expect(externalAdapter.checkedEntities).toHaveLength(2)
+    })
+
+    it('supports suffix glob patterns', () => {
+      const defaultAdapter = new TrackingAdapter('default')
+      const readonlyAdapter = new TrackingAdapter('readonly')
+
+      const composite = new CompositeAuthAdapter({
+        default: defaultAdapter,
+        mapping: { '*-readonly': readonlyAdapter }
+      })
+
+      composite.canPerform('products-readonly', 'read')
+      composite.canPerform('products', 'read')
+
+      expect(readonlyAdapter.checkedEntities).toHaveLength(1)
+      expect(defaultAdapter.checkedEntities).toHaveLength(1)
+    })
+  })
+
+  describe('getCurrentUser', () => {
+    it('returns user from default adapter', () => {
+      const defaultAdapter = new TrackingAdapter('admin')
+      const externalAdapter = new TrackingAdapter('service')
+
+      const composite = new CompositeAuthAdapter({
+        default: defaultAdapter,
+        mapping: { 'external-*': externalAdapter }
+      })
+
+      expect(composite.getCurrentUser()).toEqual({ name: 'admin' })
+    })
+  })
+
+  describe('factory integration', () => {
+    it('resolves adapters in mapping via factory', () => {
+      const defaultAdapter = new PermissiveAuthAdapter()
+
+      const composite = new CompositeAuthAdapter(
+        {
+          default: defaultAdapter,
+          mapping: {
+            products: { type: 'test' }
+          }
+        },
+        { authTypes: { test: TestAuthAdapter } }
+      )
+
+      // Products should use TestAuthAdapter
+      expect(composite._getAdapter('products')).toBeInstanceOf(TestAuthAdapter)
+      // Others use default
+      expect(composite._getAdapter('books')).toBe(defaultAdapter)
+    })
+  })
+
+  describe('getAdapterInfo', () => {
+    it('returns debug info about adapters', () => {
+      const composite = new CompositeAuthAdapter({
+        default: new PermissiveAuthAdapter(),
+        mapping: {
+          products: new TestAuthAdapter(),
+          'external-*': new TrackingAdapter('ext')
+        }
+      })
+
+      const info = composite.getAdapterInfo()
+
+      expect(info.default).toBe('PermissiveAuthAdapter')
+      expect(info.exactMatches.products).toBe('TestAuthAdapter')
+      expect(info.patterns).toHaveLength(1)
+      expect(info.patterns[0].pattern).toBe('external-*')
+      expect(info.patterns[0].adapter).toBe('TrackingAdapter')
+    })
+  })
+})

package/src/entity/auth/index.js

@@ -3,6 +3,10 @@
  *
  * AuthAdapter interface and implementations for scope/silo permission checks.
  * Includes Symfony-inspired role hierarchy and security checker.
+ *
+ * Multi-source auth:
+ * - CompositeAuthAdapter routes to different adapters based on entity patterns
+ * - authFactory normalizes config (instance, string, or object)
  */
 
 // Interface
@@ -16,3 +20,13 @@ export { SecurityChecker, createSecurityChecker } from './SecurityChecker.js'
 
 // Implementations
 export { PermissiveAuthAdapter, createPermissiveAdapter } from './PermissiveAdapter.js'
+export { CompositeAuthAdapter, createCompositeAuthAdapter } from './CompositeAuthAdapter.js'
+
+// Factory/Resolver pattern (like storage/factory.js)
+export {
+  authFactory,
+  createAuthFactory,
+  authTypes,
+  parseAuthPattern,
+  defaultAuthResolver
+} from './factory.js'

package/src/entity/storage/MockApiStorage.js

@@ -29,7 +29,23 @@ export class MockApiStorage extends IStorage {
    * - supportsTotal: true - Returns accurate total from in-memory data
    * - supportsFilters: true - Filters in-memory via list() params
    * - supportsPagination: true - Paginates in-memory
-   * - supportsCaching: false - Already in-memory, no cache benefit
+   * - supportsCaching: false - Suggests EntityManager cache is not useful (see below)
+   *
+   * WHY supportsCaching = false?
+   * MockApiStorage is already in-memory, so the primary benefit of caching (avoiding
+   * network calls) doesn't apply. However, EntityManager cache CAN still be enabled
+   * by subclassing and setting supportsCaching: true. This is useful when you need:
+   * - Parent field resolution for searchFields (e.g., 'book.title' in loans)
+   * - Warmup at boot for consistent initial state
+   * - Local filtering without re-calling list()
+   *
+   * To enable EntityManager caching on MockApiStorage:
+   * ```js
+   * class CacheableMockStorage extends MockApiStorage {
+   *   static capabilities = { ...MockApiStorage.capabilities, supportsCaching: true }
+   *   get supportsCaching() { return true }
+   * }
+   * ```
    *
    * @type {import('./index.js').StorageCapabilities}
    */
@@ -49,13 +65,26 @@ export class MockApiStorage extends IStorage {
     return MockApiStorage.capabilities.supportsCaching
   }
 
+  /**
+   * Instance capabilities getter.
+   * Merges static capabilities with instance-specific ones like requiresAuth.
+   * @returns {object}
+   */
+  get capabilities() {
+    return {
+      ...MockApiStorage.capabilities,
+      requiresAuth: !!this._authCheck
+    }
+  }
+
   constructor(options = {}) {
     super()
     const {
       entityName,
       idField = 'id',
       generateId = () => Date.now().toString(36) + Math.random().toString(36).substr(2),
-      initialData = null
+      initialData = null,
+      authCheck = null // Optional: () => boolean - throws 401 if returns false
     } = options
 
     if (!entityName) {
@@ -67,11 +96,24 @@ export class MockApiStorage extends IStorage {
     this.generateId = generateId
     this._storageKey = `mockapi_${entityName}_data`
     this._data = new Map()
+    this._authCheck = authCheck
 
     // Load from localStorage or seed with initialData
     this._loadFromStorage(initialData)
   }
 
+  /**
+   * Check authentication if authCheck is configured
+   * @throws {Error} 401 error if not authenticated
+   */
+  _checkAuth() {
+    if (this._authCheck && !this._authCheck()) {
+      const error = new Error(`Unauthorized: Authentication required to access ${this.entityName}`)
+      error.status = 401
+      throw error
+    }
+  }
+
   /**
    * Load data from localStorage, seed with initialData if empty
    * @param {Array|null} initialData - Data to seed if storage is empty
@@ -142,6 +184,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<{ items: Array, total: number }>}
    */
   async list(params = {}) {
+    this._checkAuth()
     const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {}, search } = params
 
     let items = this._getAll()
@@ -197,6 +240,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async get(id) {
+    this._checkAuth()
     const item = this._data.get(String(id))
     if (!item) {
       const error = new Error(`Entity not found: ${id}`)
@@ -212,6 +256,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<Array<object>>}
    */
   async getMany(ids) {
+    this._checkAuth()
     if (!ids || ids.length === 0) return []
     const results = []
     for (const id of ids) {
@@ -266,6 +311,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async create(data) {
+    this._checkAuth()
     const id = data[this.idField] || this.generateId()
     const newItem = {
       ...data,
@@ -284,6 +330,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async update(id, data) {
+    this._checkAuth()
     if (!this._data.has(String(id))) {
       const error = new Error(`Entity not found: ${id}`)
       error.status = 404
@@ -306,6 +353,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async patch(id, data) {
+    this._checkAuth()
     const existing = this._data.get(String(id))
     if (!existing) {
       const error = new Error(`Entity not found: ${id}`)
@@ -328,6 +376,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<void>}
    */
   async delete(id) {
+    this._checkAuth()
     if (!this._data.has(String(id))) {
       const error = new Error(`Entity not found: ${id}`)
       error.status = 404

package/src/entity/storage/index.js

@@ -19,7 +19,14 @@
  * @property {boolean} [supportsTotal=false] - Storage `list()` returns `{ items, total }` with accurate total count
  * @property {boolean} [supportsFilters=false] - Storage `list()` accepts `filters` param and handles filtering
  * @property {boolean} [supportsPagination=false] - Storage `list()` accepts `page`/`page_size` params
- * @property {boolean} [supportsCaching=false] - Storage benefits from EntityManager cache layer (network-based storages)
+ * @property {boolean} [supportsCaching=false] - Hint to EntityManager: should it cache this storage's results?
+ *   This is a RECOMMENDATION, not a capability. The storage suggests whether EntityManager caching is useful:
+ *   - `true`: Cache is beneficial (remote APIs, slow storages) - enables local filtering, parent field
+ *     resolution, warmup at boot
+ *   - `false`: Cache adds no value (already in-memory storages like MockApiStorage) - but still technically
+ *     possible if overridden. Set to `false` when storage is already fast and in-memory.
+ *   Use `false` for: in-memory storages, real-time data sources, storages with their own cache layer.
+ *   Use `true` for: REST APIs, database backends, any storage where avoiding repeat fetches helps.
  * @property {string[]} [searchFields] - Fields to search when filtering locally. Supports own fields ('title')
  *   and parent entity fields ('book.title') via EntityManager.parents config. When undefined, all string
  *   fields are searched (default behavior). When defined, only listed fields are searched.
@@ -40,7 +47,7 @@
  *     supportsTotal: true,
  *     supportsFilters: true,
  *     supportsPagination: true,
- *     supportsCaching: true // set to false for in-memory storages
+ *     supportsCaching: true // false = "not useful" (in-memory), true = "beneficial" (remote API)
  *   }
  *
  *   // Backward-compat instance getter (optional, for smooth migration)

package/src/index.js

@@ -47,5 +47,12 @@ export * from './query/index.js'
 // Utils
 export * from './utils/index.js'
 
+// Toast (signal-based notifications)
+export * from './toast/index.js'
+
+// Debug tools are NOT exported here to enable tree-shaking.
+// Import from 'qdadm/debug' separately when needed:
+//   import { debugBar, DebugModule } from 'qdadm/debug'
+
 // Assets
 export { default as qdadmLogo } from './assets/logo.svg'