qdadm 0.27.0 → 0.28.0

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
+}

package/src/entity/factory.test.js

@@ -0,0 +1,189 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  managerFactory,
+  defaultManagerResolver,
+  createManagerFactory,
+  createManagers
+} from './factory.js'
+import { EntityManager } from './EntityManager.js'
+import { ApiStorage } from './storage/ApiStorage.js'
+import { MemoryStorage } from './storage/MemoryStorage.js'
+
+describe('defaultManagerResolver', () => {
+  it('creates EntityManager with config', () => {
+    const storage = new MemoryStorage()
+    const config = { storage, label: 'Bot' }
+
+    const manager = defaultManagerResolver(config, 'bots')
+
+    expect(manager).toBeInstanceOf(EntityManager)
+    expect(manager.name).toBe('bots')
+    expect(manager.storage).toBe(storage)
+  })
+
+  it('uses registered manager class from registry', () => {
+    class CustomManager extends EntityManager {}
+    const storage = new MemoryStorage()
+    const config = { storage }
+    const context = { managerRegistry: { bots: CustomManager } }
+
+    const manager = defaultManagerResolver(config, 'bots', context)
+
+    expect(manager).toBeInstanceOf(CustomManager)
+  })
+
+  it('falls back to EntityManager when not in registry', () => {
+    const storage = new MemoryStorage()
+    const config = { storage }
+    const context = { managerRegistry: { other: class extends EntityManager {} } }
+
+    const manager = defaultManagerResolver(config, 'bots', context)
+
+    expect(manager).toBeInstanceOf(EntityManager)
+    expect(manager.constructor).toBe(EntityManager)
+  })
+})
+
+describe('managerFactory', () => {
+  it('returns EntityManager instance directly', () => {
+    const manager = new EntityManager({ name: 'test', storage: new MemoryStorage() })
+    const result = managerFactory(manager, 'test')
+    expect(result).toBe(manager)
+  })
+
+  it('returns duck-typed manager directly', () => {
+    const duckManager = {
+      storage: new MemoryStorage(),
+      list: () => Promise.resolve({ items: [], total: 0 }),
+      get: () => Promise.resolve(null)
+    }
+    const result = managerFactory(duckManager, 'test')
+    expect(result).toBe(duckManager)
+  })
+
+  it('creates manager from string pattern', () => {
+    const result = managerFactory('api:/api/bots', 'bots')
+    expect(result).toBeInstanceOf(EntityManager)
+    expect(result.storage).toBeInstanceOf(ApiStorage)
+    expect(result.storage.endpoint).toBe('/api/bots')
+  })
+
+  it('creates manager from config object with storage string', () => {
+    const result = managerFactory({
+      storage: 'api:/api/tasks',
+      label: 'Task'
+    }, 'tasks')
+
+    expect(result).toBeInstanceOf(EntityManager)
+    expect(result.storage).toBeInstanceOf(ApiStorage)
+  })
+
+  it('uses storage instance directly from config', () => {
+    const storage = new MemoryStorage()
+    const result = managerFactory({ storage }, 'items')
+
+    expect(result).toBeInstanceOf(EntityManager)
+    expect(result.storage).toBe(storage)
+  })
+
+  it('uses custom storageResolver', () => {
+    const customStorage = new MemoryStorage()
+    const storageResolver = vi.fn().mockReturnValue(customStorage)
+    const context = { storageResolver }
+
+    const result = managerFactory('api:/test', 'test', context)
+
+    expect(storageResolver).toHaveBeenCalled()
+    expect(result.storage).toBe(customStorage)
+  })
+
+  it('uses custom managerResolver', () => {
+    class CustomManager extends EntityManager {}
+    const managerResolver = vi.fn().mockImplementation((config, name) => {
+      return new CustomManager({ name, ...config })
+    })
+    const context = { managerResolver }
+
+    const result = managerFactory('api:/test', 'test', context)
+
+    expect(managerResolver).toHaveBeenCalled()
+    expect(result).toBeInstanceOf(CustomManager)
+  })
+
+  it('uses managerRegistry for generated classes', () => {
+    class BotManager extends EntityManager {}
+    const context = { managerRegistry: { bots: BotManager } }
+
+    const result = managerFactory('api:/api/bots', 'bots', context)
+
+    expect(result).toBeInstanceOf(BotManager)
+  })
+
+  it('throws for invalid config', () => {
+    expect(() => managerFactory(123, 'test'))
+      .toThrow('Invalid manager config')
+  })
+})
+
+describe('createManagerFactory', () => {
+  it('creates factory with bound context', () => {
+    class CustomManager extends EntityManager {}
+    const context = { managerRegistry: { bots: CustomManager } }
+    const factory = createManagerFactory(context)
+
+    const result = factory('api:/api/bots', 'bots')
+
+    expect(result).toBeInstanceOf(CustomManager)
+  })
+})
+
+describe('createManagers', () => {
+  it('creates managers from config object', () => {
+    const config = {
+      bots: 'api:/api/bots',
+      tasks: { storage: 'memory:tasks', label: 'Task' }
+    }
+
+    const managers = createManagers(config)
+
+    expect(managers.bots).toBeInstanceOf(EntityManager)
+    expect(managers.bots.storage).toBeInstanceOf(ApiStorage)
+    expect(managers.tasks).toBeInstanceOf(EntityManager)
+    expect(managers.tasks.storage).toBeInstanceOf(MemoryStorage)
+  })
+
+  it('uses context for all managers', () => {
+    class BotManager extends EntityManager {}
+    class TaskManager extends EntityManager {}
+    const context = {
+      managerRegistry: { bots: BotManager, tasks: TaskManager }
+    }
+    const config = {
+      bots: 'api:/api/bots',
+      tasks: 'api:/api/tasks'
+    }
+
+    const managers = createManagers(config, context)
+
+    expect(managers.bots).toBeInstanceOf(BotManager)
+    expect(managers.tasks).toBeInstanceOf(TaskManager)
+  })
+
+  it('passes through existing manager instances', () => {
+    const existingManager = new EntityManager({ name: 'existing', storage: new MemoryStorage() })
+    const config = {
+      bots: 'api:/api/bots',
+      existing: existingManager
+    }
+
+    const managers = createManagers(config)
+
+    expect(managers.existing).toBe(existingManager)
+    expect(managers.bots).toBeInstanceOf(EntityManager)
+  })
+
+  it('returns empty object for empty config', () => {
+    const managers = createManagers({})
+    expect(managers).toEqual({})
+  })
+})

package/src/entity/index.js

@@ -7,6 +7,14 @@
 // EntityManager
 export { EntityManager, createEntityManager } from './EntityManager.js'
 
+// Manager Factory
+export {
+  managerFactory,
+  defaultManagerResolver,
+  createManagerFactory,
+  createManagers
+} from './factory.js'
+
 // Storage adapters
 export * from './storage/index.js'
 

package/src/entity/storage/ApiStorage.js

@@ -1,3 +1,5 @@
+import { IStorage } from './IStorage.js'
+
 /**
  * ApiStorage - REST API storage adapter
  *
@@ -20,7 +22,7 @@
  * })
  * ```
  */
-export class ApiStorage {
+export class ApiStorage extends IStorage {
   /**
    * Storage capabilities declaration.
    * Describes what features this storage adapter supports.
@@ -44,6 +46,7 @@ export class ApiStorage {
   }
 
   constructor(options = {}) {
+    super()
     const {
       endpoint,
       client = null,

package/src/entity/storage/IStorage.js

@@ -0,0 +1,76 @@
+/**
+ * IStorage - Base class for storage adapters
+ *
+ * Provides instanceof checking for storageFactory.
+ * All storage adapters should extend this class.
+ *
+ * Usage:
+ * ```js
+ * class MyStorage extends IStorage {
+ *   static capabilities = { supportsTotal: true, ... }
+ *   async list(params) { ... }
+ *   async get(id) { ... }
+ *   async create(data) { ... }
+ *   async update(id, data) { ... }
+ *   async delete(id) { ... }
+ * }
+ * ```
+ */
+export class IStorage {
+  /**
+   * Default capabilities - override in subclass
+   * @type {import('./index.js').StorageCapabilities}
+   */
+  static capabilities = {
+    supportsTotal: false,
+    supportsFilters: false,
+    supportsPagination: false,
+    supportsCaching: false
+  }
+
+  /**
+   * List entities with optional filtering/pagination
+   * @param {object} params - Query parameters
+   * @returns {Promise<{items: Array, total?: number}>}
+   */
+  async list(params = {}) {
+    throw new Error('list() not implemented')
+  }
+
+  /**
+   * Get single entity by ID
+   * @param {string} id - Entity ID
+   * @returns {Promise<object|null>}
+   */
+  async get(id) {
+    throw new Error('get() not implemented')
+  }
+
+  /**
+   * Create new entity
+   * @param {object} data - Entity data
+   * @returns {Promise<object>} Created entity with ID
+   */
+  async create(data) {
+    throw new Error('create() not implemented')
+  }
+
+  /**
+   * Update entity by ID
+   * @param {string} id - Entity ID
+   * @param {object} data - Updated data
+   * @returns {Promise<object>} Updated entity
+   */
+  async update(id, data) {
+    throw new Error('update() not implemented')
+  }
+
+  /**
+   * Delete entity by ID
+   * @param {string} id - Entity ID
+   * @returns {Promise<void>}
+   */
+  async delete(id) {
+    throw new Error('delete() not implemented')
+  }
+}

package/src/entity/storage/LocalStorage.js

@@ -1,3 +1,5 @@
+import { IStorage } from './IStorage.js'
+
 /**
  * LocalStorage - Browser localStorage storage adapter
  *
@@ -17,7 +19,7 @@
  * })
  * ```
  */
-export class LocalStorage {
+export class LocalStorage extends IStorage {
   /**
    * Storage capabilities declaration.
    * Describes what features this storage adapter supports.
@@ -47,6 +49,7 @@ export class LocalStorage {
   }
 
   constructor(options = {}) {
+    super()
     const {
       key,
       idField = 'id',

package/src/entity/storage/MemoryStorage.js

@@ -1,3 +1,5 @@
+import { IStorage } from './IStorage.js'
+
 /**
  * MemoryStorage - In-memory storage adapter
  *
@@ -17,7 +19,7 @@
  * })
  * ```
  */
-export class MemoryStorage {
+export class MemoryStorage extends IStorage {
   /**
    * Storage capabilities declaration.
    * Describes what features this storage adapter supports.
@@ -47,6 +49,7 @@ export class MemoryStorage {
   }
 
   constructor(options = {}) {
+    super()
     const {
       idField = 'id',
       generateId = () => Date.now().toString(36) + Math.random().toString(36).substr(2),

package/src/entity/storage/MockApiStorage.js

@@ -1,3 +1,5 @@
+import { IStorage } from './IStorage.js'
+
 /**
  * MockApiStorage - In-memory storage with localStorage persistence
  *
@@ -18,7 +20,7 @@
  *
  * localStorage key pattern: mockapi_${entityName}_data
  */
-export class MockApiStorage {
+export class MockApiStorage extends IStorage {
   /**
    * Storage capabilities declaration.
    * Describes what features this storage adapter supports.
@@ -48,6 +50,7 @@ export class MockApiStorage {
   }
 
   constructor(options = {}) {
+    super()
     const {
       entityName,
       idField = 'id',

package/src/entity/storage/SdkStorage.js

@@ -1,3 +1,5 @@
+import { IStorage } from './IStorage.js'
+
 /**
  * SdkStorage - hey-api SDK storage adapter
  *
@@ -93,7 +95,7 @@
  * })
  * ```
  */
-export class SdkStorage {
+export class SdkStorage extends IStorage {
   /**
    * Storage capabilities declaration
    * @type {import('./index.js').StorageCapabilities}
@@ -141,6 +143,7 @@ export class SdkStorage {
    * @param {boolean} [options.clientSidePagination=false] - Enable client-side pagination for list()
    */
   constructor(options = {}) {
+    super()
     const {
       sdk = null,
       getSdk = null,