qdadm 0.26.3 → 0.28.0

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,

package/src/entity/storage/factory.js

@@ -0,0 +1,193 @@
+/**
+ * Storage Factory/Resolver Pattern
+ *
+ * Enables declarative storage configuration with auto-resolution.
+ *
+ * Usage:
+ * ```js
+ * // String pattern → factory parses, resolver creates
+ * storageFactory('api:/api/bots', 'bots')  // → ApiStorage
+ * storageFactory('local:settings', 'settings')  // → LocalStorage
+ * storageFactory('mock:books', 'books')  // → MockApiStorage
+ *
+ * // Config object → factory normalizes, resolver creates
+ * storageFactory({ endpoint: '/api/bots' }, 'bots')  // → ApiStorage
+ * storageFactory({ type: 'local', key: 'my-key' }, 'settings')  // → LocalStorage
+ *
+ * // Storage instance → returned directly
+ * storageFactory(myStorageInstance, 'bots')  // → myStorageInstance
+ * ```
+ */
+
+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'
+import { SdkStorage } from './SdkStorage.js'
+
+/**
+ * Storage type registry - maps type names to storage classes
+ * @type {Record<string, typeof IStorage>}
+ */
+export const storageTypes = {
+  api: ApiStorage,
+  local: LocalStorage,
+  memory: MemoryStorage,
+  mock: MockApiStorage,
+  sdk: SdkStorage
+}
+
+/**
+ * Parse string pattern 'type:endpoint' into config object
+ *
+ * @param {string} pattern - Storage pattern (e.g., 'api:/api/bots', 'local:settings')
+ * @returns {{type: string, endpoint?: string, key?: string} | null} Parsed config or null if invalid
+ *
+ * @example
+ * parseStoragePattern('api:/api/bots')  // → { type: 'api', endpoint: '/api/bots' }
+ * parseStoragePattern('local:settings')  // → { type: 'local', key: 'settings' }
+ * parseStoragePattern('/api/bots')  // → { type: 'api', endpoint: '/api/bots' }
+ */
+export function parseStoragePattern(pattern) {
+  if (typeof pattern !== 'string') return null
+
+  // Pattern: 'type:value'
+  const match = pattern.match(/^(\w+):(.+)$/)
+  if (match) {
+    const [, type, value] = match
+    // For local/mock, value is key/name; for api/sdk, value is endpoint
+    if (type === 'local' || type === 'memory') {
+      return { type, key: value }
+    }
+    if (type === 'mock') {
+      return { type, entityName: value }
+    }
+    return { type, endpoint: value }
+  }
+
+  // Plain string starting with '/' → assume API endpoint
+  if (pattern.startsWith('/')) {
+    return { type: 'api', endpoint: pattern }
+  }
+
+  return null
+}
+
+/**
+ * Default storage resolver - creates storage instance from config
+ *
+ * Override this via Kernel config for custom storage types.
+ *
+ * @param {object} config - Normalized storage config with `type` property
+ * @param {string} entityName - Entity name (used for key generation)
+ * @returns {IStorage} Storage instance
+ *
+ * @example
+ * defaultStorageResolver({ type: 'api', endpoint: '/api/bots' }, 'bots')
+ * defaultStorageResolver({ type: 'local', key: 'settings' }, 'settings')
+ */
+export function defaultStorageResolver(config, entityName) {
+  const { type, ...rest } = config
+
+  const StorageClass = storageTypes[type]
+  if (!StorageClass) {
+    throw new Error(`Unknown storage type: "${type}". Available: ${Object.keys(storageTypes).join(', ')}`)
+  }
+
+  // Add entityName to config if not present (useful for mock/memory)
+  if (!rest.entityName && !rest.key) {
+    if (type === 'local' || type === 'memory') {
+      rest.key = entityName
+    } else if (type === 'mock') {
+      rest.entityName = entityName
+    }
+  }
+
+  return new StorageClass(rest)
+}
+
+/**
+ * Storage factory - normalizes input and delegates to resolver
+ *
+ * Handles:
+ * - IStorage instance → return directly
+ * - String pattern 'type:endpoint' → parse and resolve
+ * - Plain string '/endpoint' → treat as API endpoint
+ * - Config object → normalize and resolve
+ *
+ * @param {IStorage | string | object} config - Storage config (instance, pattern, or object)
+ * @param {string} entityName - Entity name for key generation
+ * @param {function} [resolver=defaultStorageResolver] - Custom resolver function
+ * @returns {IStorage} Storage instance
+ *
+ * @example
+ * // Instance passthrough
+ * storageFactory(myStorage, 'bots')  // → myStorage
+ *
+ * // String patterns
+ * storageFactory('api:/api/bots', 'bots')  // → ApiStorage
+ * storageFactory('/api/bots', 'bots')  // → ApiStorage (default type)
+ * storageFactory('local:settings', 'settings')  // → LocalStorage
+ *
+ * // Config objects
+ * storageFactory({ endpoint: '/api/bots' }, 'bots')  // → ApiStorage
+ * storageFactory({ type: 'local' }, 'settings')  // → LocalStorage
+ */
+export function storageFactory(config, entityName, resolver = defaultStorageResolver) {
+  // Already a Storage instance → return directly
+  if (config instanceof IStorage) {
+    return config
+  }
+
+  // Also check for duck-typed storage (has list method and isn't a class)
+  if (config && typeof config === 'object' && typeof config.list === 'function' && typeof config.get === 'function') {
+    return config
+  }
+
+  // String pattern → parse
+  if (typeof config === 'string') {
+    const parsed = parseStoragePattern(config)
+    if (!parsed) {
+      throw new Error(`Invalid storage pattern: "${config}". Use 'type:value' or '/api/endpoint'`)
+    }
+    return resolver(parsed, entityName)
+  }
+
+  // Config object → normalize
+  if (config && typeof config === 'object') {
+    // If no type, infer from properties
+    if (!config.type) {
+      if (config.endpoint) {
+        config = { type: 'api', ...config }
+      } else if (config.key) {
+        config = { type: 'local', ...config }
+      } else if (config.initialData) {
+        config = { type: 'mock', ...config }
+      } else {
+        throw new Error(`Cannot infer storage type from config: ${JSON.stringify(config)}. Add 'type' property.`)
+      }
+    }
+    return resolver(config, entityName)
+  }
+
+  throw new Error(`Invalid storage config: ${typeof config}. Expected string, object, or Storage instance.`)
+}
+
+/**
+ * Create a custom storage factory with overridden resolver
+ *
+ * @param {function} customResolver - Custom resolver that handles additional types
+ * @returns {function} Storage factory with custom resolver
+ *
+ * @example
+ * const myFactory = createStorageFactory((config, entityName) => {
+ *   if (config.type === 'graphql') {
+ *     return new GraphQLStorage(config)
+ *   }
+ *   return defaultStorageResolver(config, entityName)
+ * })
+ */
+export function createStorageFactory(customResolver) {
+  return (config, entityName) => storageFactory(config, entityName, customResolver)
+}