@quazardous/qdadm 1.19.3

package/src/entity/factory.test.js

@@ -0,0 +1,189 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  managerFactory,
+  defaultManagerResolver,
+  createManagerFactory,
+  createManagers
+} from './factory'
+import { EntityManager } from './EntityManager'
+import { ApiStorage } from './storage/ApiStorage'
+import { MemoryStorage } from './storage/MemoryStorage'
+
+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/factory.ts

@@ -0,0 +1,146 @@
+/**
+ * Manager Factory/Resolver Pattern
+ *
+ * Enables declarative manager configuration with auto-resolution.
+ * Works with storageFactory for complete auto-wiring.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { EntityManager } from './EntityManager'
+import { storageFactory } from './storage/factory'
+
+/**
+ * Manager config interface
+ */
+export interface ManagerConfig {
+  name?: string
+  storage?: any
+  label?: string
+  labelPlural?: string
+  fields?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+/**
+ * Manager factory context
+ */
+export interface ManagerFactoryContext {
+  managerRegistry?: Record<string, typeof EntityManager>
+  storageResolver?: (config: any, entityName: string) => any
+  managerResolver?: ManagerResolver
+  [key: string]: unknown
+}
+
+/**
+ * Manager resolver function type
+ */
+export type ManagerResolver = (
+  config: ManagerConfig,
+  entityName: string,
+  context: ManagerFactoryContext
+) => EntityManager
+
+/**
+ * Default manager resolver - creates manager instance from config
+ */
+export function defaultManagerResolver(
+  config: ManagerConfig,
+  entityName: string,
+  context: ManagerFactoryContext = {}
+): EntityManager {
+  const { managerRegistry = {} } = context
+
+  // Look up registered manager class
+  const ManagerClass = managerRegistry[entityName] || EntityManager
+
+  // Ensure name is set
+  const managerConfig = {
+    name: entityName,
+    ...config
+  }
+
+  return new ManagerClass(managerConfig as any)
+}
+
+/**
+ * Manager factory - normalizes input and delegates to resolver
+ */
+export function managerFactory(
+  config: EntityManager | string | ManagerConfig,
+  entityName: string,
+  context: ManagerFactoryContext = {}
+): EntityManager {
+  const {
+    storageResolver,
+    managerResolver = defaultManagerResolver
+  } = context
+
+  // Already a Manager instance → return directly
+  if (config instanceof EntityManager) {
+    return config
+  }
+
+  // Also check for duck-typed manager
+  if (
+    config &&
+    typeof config === 'object' &&
+    'storage' in config &&
+    typeof (config as any).list === 'function'
+  ) {
+    return config as any
+  }
+
+  // String pattern → treat as storage config
+  if (typeof config === 'string') {
+    const storage = storageFactory(config, entityName, storageResolver as any)
+    return managerResolver({ storage }, entityName, context)
+  }
+
+  // Config object → resolve storage first, then manager
+  if (config && typeof config === 'object') {
+    const resolvedConfig = { ...config }
+
+    // Resolve storage if provided as string/config
+    if (config.storage && typeof config.storage === 'string') {
+      resolvedConfig.storage = storageFactory(config.storage, entityName, storageResolver as any)
+    } else if (
+      config.storage &&
+      typeof config.storage === 'object' &&
+      typeof (config.storage as any).list !== 'function'
+    ) {
+      resolvedConfig.storage = storageFactory(config.storage as any, entityName, storageResolver as any)
+    }
+
+    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
+ */
+export function createManagerFactory(
+  context: ManagerFactoryContext
+): (config: EntityManager | string | ManagerConfig, entityName: string) => EntityManager {
+  return (config, entityName) => managerFactory(config, entityName, context)
+}
+
+/**
+ * Create all managers from a config object
+ */
+export function createManagers(
+  managersConfig: Record<string, EntityManager | string | ManagerConfig>,
+  context: ManagerFactoryContext = {}
+): Record<string, EntityManager> {
+  const managers: Record<string, EntityManager> = {}
+
+  for (const [entityName, config] of Object.entries(managersConfig)) {
+    managers[entityName] = managerFactory(config, entityName, context)
+  }
+
+  return managers
+}

package/src/entity/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Entity Module
+ *
+ * EntityManager and storage adapters for data abstraction.
+ */
+
+// EntityManager
+export {
+  EntityManager,
+  createEntityManager,
+  type EntityManagerOptions,
+  type RoutingContext,
+  type PresaveContext,
+  type PostsaveContext,
+  type PredeleteContext,
+  type QueryOptions,
+  type WhitelistContext,
+  type CacheInfo
+} from './EntityManager'
+
+// Re-export types from types module
+export type {
+  EntityRecord,
+  ListParams,
+  ListResult,
+  FieldConfig,
+  ChildConfig,
+  ParentConfig,
+  RelationConfig,
+  NavConfig,
+  StorageCapabilities
+} from '../types'
+
+// Manager Factory
+export {
+  managerFactory,
+  defaultManagerResolver,
+  createManagerFactory,
+  createManagers,
+  type ManagerConfig,
+  type ManagerFactoryContext,
+  type ManagerResolver
+} from './factory'
+
+// Storage adapters
+export * from './storage/index'
+
+// Auth adapters
+export * from './auth'

package/src/entity/storage/ApiStorage.ts

@@ -0,0 +1,228 @@
+import { IStorage } from './IStorage'
+import type { EntityRecord, ListParams, ListResult, StorageCapabilities } from '../../types'
+
+/**
+ * HTTP client interface compatible with axios
+ */
+export interface HttpClient {
+  get<T = unknown>(url: string, config?: { params?: Record<string, unknown> }): Promise<{ data: T }>
+  post<T = unknown>(url: string, data?: unknown): Promise<{ data: T }>
+  put<T = unknown>(url: string, data?: unknown): Promise<{ data: T }>
+  patch<T = unknown>(url: string, data?: unknown): Promise<{ data: T }>
+  delete<T = unknown>(url: string): Promise<{ data: T }>
+  request<T = unknown>(config: {
+    method: string
+    url: string
+    data?: unknown
+    params?: Record<string, unknown>
+    headers?: Record<string, string>
+  }): Promise<{ data: T }>
+}
+
+/**
+ * Routing context for normalize functions
+ */
+export interface RoutingContext {
+  parentChain?: Array<{ entity: string; id: string }>
+  path?: string
+}
+
+/**
+ * ApiStorage options
+ */
+export interface ApiStorageOptions<T extends EntityRecord = EntityRecord> {
+  endpoint: string
+  client?: HttpClient | null
+  getClient?: (() => HttpClient) | null
+  responseItemsKey?: string
+  responseTotalKey?: string
+  paramMapping?: Record<string, string>
+  normalize?: ((data: T, context?: RoutingContext | null) => T) | null
+  denormalize?: ((data: Partial<T>) => Partial<T>) | null
+}
+
+/**
+ * ApiStorage - REST API storage adapter
+ *
+ * Implements the storage interface for REST APIs.
+ * Expects standard response format: { items: [], total: number, page: number }
+ */
+export class ApiStorage<T extends EntityRecord = EntityRecord> extends IStorage<T> {
+  static storageName = 'ApiStorage'
+
+  static capabilities: StorageCapabilities = {
+    supportsTotal: true,
+    supportsFilters: true,
+    supportsPagination: true,
+    supportsCaching: true,
+  }
+
+  /** @deprecated Use static ApiStorage.capabilities.supportsCaching instead */
+  get supportsCaching(): boolean {
+    return ApiStorage.capabilities.supportsCaching
+  }
+
+  readonly endpoint: string
+  readonly responseItemsKey: string
+  readonly responseTotalKey: string
+  readonly paramMapping: Record<string, string>
+
+  protected _client: HttpClient | null
+  protected _getClient: (() => HttpClient) | null
+  protected _normalize: ((data: T, context?: RoutingContext | null) => T) | null
+  protected _denormalize: ((data: Partial<T>) => Partial<T>) | null
+
+  constructor(options: ApiStorageOptions<T>) {
+    super()
+    const {
+      endpoint,
+      client = null,
+      getClient = null,
+      responseItemsKey = 'items',
+      responseTotalKey = 'total',
+      paramMapping = {},
+      normalize = null,
+      denormalize = null,
+    } = options
+
+    this.endpoint = endpoint
+    this._client = client
+    this._getClient = getClient
+    this.responseItemsKey = responseItemsKey
+    this.responseTotalKey = responseTotalKey
+    this.paramMapping = paramMapping
+    this._normalize = normalize
+    this._denormalize = denormalize
+  }
+
+  /**
+   * Apply parameter mapping to transform filter names
+   */
+  protected _applyParamMapping(params: Record<string, unknown>): Record<string, unknown> {
+    if (!this.paramMapping || Object.keys(this.paramMapping).length === 0) {
+      return params
+    }
+    const mapped: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(params)) {
+      const mappedKey = this.paramMapping[key] || key
+      mapped[mappedKey] = value
+    }
+    return mapped
+  }
+
+  /**
+   * Normalize API response data to internal format
+   */
+  protected _normalizeData(data: T | T[], context: RoutingContext | null = null): T | T[] {
+    if (!this._normalize) return data
+    if (Array.isArray(data)) {
+      return data.map((item) => this._normalize!(item, context))
+    }
+    return this._normalize(data, context)
+  }
+
+  /**
+   * Denormalize internal data to API format
+   */
+  protected _denormalizeData(data: Partial<T>): Partial<T> {
+    if (!this._denormalize) return data
+    return this._denormalize(data)
+  }
+
+  get client(): HttpClient {
+    if (this._getClient) {
+      return this._getClient()
+    }
+    if (!this._client) {
+      throw new Error('ApiStorage: No HTTP client configured')
+    }
+    return this._client
+  }
+
+  set client(value: HttpClient) {
+    this._client = value
+  }
+
+  async list(params: ListParams = {}, context: RoutingContext | null = null): Promise<ListResult<T>> {
+    const { page = 1, page_size = 20, sort_by, sort_order, filters = {} } = params
+
+    const mappedFilters = this._applyParamMapping(filters)
+
+    const response = await this.client.get<Record<string, unknown>>(this.endpoint, {
+      params: { page, page_size, sort_by, sort_order, ...mappedFilters },
+    })
+
+    const data = response.data
+    const rawItems = (data[this.responseItemsKey] || data.items || data) as T[]
+    const items = this._normalizeData(rawItems, context) as T[]
+
+    return {
+      items,
+      total:
+        (data[this.responseTotalKey] as number) ||
+        (data.total as number) ||
+        (Array.isArray(data) ? data.length : 0),
+    }
+  }
+
+  async get(id: string | number, context: RoutingContext | null = null): Promise<T> {
+    const response = await this.client.get<T>(`${this.endpoint}/${id}`)
+    return this._normalizeData(response.data, context) as T
+  }
+
+  async create(data: Partial<T>): Promise<T> {
+    const apiData = this._denormalizeData(data)
+    const response = await this.client.post<T>(this.endpoint, apiData)
+    return this._normalizeData(response.data) as T
+  }
+
+  async update(id: string | number, data: Partial<T>): Promise<T> {
+    const apiData = this._denormalizeData(data)
+    const response = await this.client.put<T>(`${this.endpoint}/${id}`, apiData)
+    return this._normalizeData(response.data) as T
+  }
+
+  async patch(id: string | number, data: Partial<T>): Promise<T> {
+    const apiData = this._denormalizeData(data)
+    const response = await this.client.patch<T>(`${this.endpoint}/${id}`, apiData)
+    return this._normalizeData(response.data) as T
+  }
+
+  async delete(id: string | number): Promise<void> {
+    await this.client.delete(`${this.endpoint}/${id}`)
+  }
+
+  /**
+   * Generic request for special operations
+   */
+  async request<R = T>(
+    method: string,
+    endpoint: string,
+    options: {
+      data?: unknown
+      params?: Record<string, unknown>
+      headers?: Record<string, string>
+      context?: RoutingContext | null
+    } = {}
+  ): Promise<R> {
+    const { context, ...requestOptions } = options
+    const url = endpoint.startsWith('/') ? endpoint : `${this.endpoint}/${endpoint}`
+    const response = await this.client.request<R>({
+      method,
+      url,
+      data: requestOptions.data,
+      params: requestOptions.params,
+      headers: requestOptions.headers,
+    })
+    return this._normalizeData(response.data as unknown as T, context) as unknown as R
+  }
+}
+
+/**
+ * Factory function to create an ApiStorage
+ */
+export function createApiStorage<T extends EntityRecord = EntityRecord>(
+  options: ApiStorageOptions<T>
+): ApiStorage<T> {
+  return new ApiStorage(options)
+}

package/src/entity/storage/IStorage.ts

@@ -0,0 +1,100 @@
+/**
+ * IStorage - Base class for storage adapters
+ *
+ * Provides instanceof checking for storageFactory.
+ * All storage adapters should extend this class.
+ *
+ * Usage:
+ * ```ts
+ * class MyStorage extends IStorage<MyEntity> {
+ *   static capabilities = { supportsTotal: true, ... }
+ *   async list(params) { ... }
+ *   async get(id) { ... }
+ *   async create(data) { ... }
+ *   async update(id, data) { ... }
+ *   async delete(id) { ... }
+ * }
+ * ```
+ */
+
+import type { EntityRecord, ListParams, ListResult, StorageCapabilities } from '../../types'
+
+/**
+ * Abstract base class for storage adapters
+ */
+export abstract class IStorage<T extends EntityRecord = EntityRecord> {
+  /**
+   * Default capabilities - override in subclass
+   */
+  static capabilities: StorageCapabilities = {
+    supportsTotal: false,
+    supportsFilters: false,
+    supportsPagination: false,
+    supportsCaching: false,
+  }
+
+  /**
+   * List entities with optional filtering/pagination
+   * @param params - Query parameters
+   * @param _context - Optional context (e.g., parent entity)
+   * @returns Promise with items array and optional total count
+   */
+  async list(_params: ListParams = {}, _context?: unknown): Promise<ListResult<T>> {
+    throw new Error('list() not implemented')
+  }
+
+  /**
+   * Get single entity by ID
+   * @param _id - Entity ID
+   * @param _context - Optional context
+   * @returns Promise with entity or null if not found
+   */
+  async get(_id: string | number, _context?: unknown): Promise<T | null> {
+    throw new Error('get() not implemented')
+  }
+
+  /**
+   * Create new entity
+   * @param _data - Entity data
+   * @returns Promise with created entity including ID
+   */
+  async create(_data: Partial<T>): Promise<T> {
+    throw new Error('create() not implemented')
+  }
+
+  /**
+   * Update entity by ID (full replacement)
+   * @param _id - Entity ID
+   * @param _data - Updated data
+   * @returns Promise with updated entity
+   */
+  async update(_id: string | number, _data: Partial<T>): Promise<T> {
+    throw new Error('update() not implemented')
+  }
+
+  /**
+   * Patch entity by ID (partial update)
+   * @param _id - Entity ID
+   * @param _data - Partial data to merge
+   * @returns Promise with updated entity
+   */
+  async patch(_id: string | number, _data: Partial<T>): Promise<T> {
+    throw new Error('patch() not implemented')
+  }
+
+  /**
+   * Delete entity by ID
+   * @param _id - Entity ID
+   * @returns Promise that resolves when deleted
+   */
+  async delete(_id: string | number): Promise<void> {
+    throw new Error('delete() not implemented')
+  }
+
+  /**
+   * Reset storage state (for testing/development)
+   */
+  reset(): void {
+    // Default no-op, override if needed
+  }
+}