qdadm 0.18.0 → 0.26.0

package/src/entity/storage/index.js

@@ -5,6 +5,111 @@
  * EntityManagers can use these or implement their own storage.
  */
 
+/**
+ * Storage Capabilities Interface
+ *
+ * Static capabilities declaration that storage adapters expose via `static capabilities = {...}`.
+ * EntityManager reads these via `storage.constructor.capabilities` to determine feature support.
+ *
+ * All properties default to `false` if not declared (conservative assumption).
+ * Custom storage implementations that don't declare capabilities will degrade gracefully
+ * via fallback to empty `{}`.
+ *
+ * @typedef {object} StorageCapabilities
+ * @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 {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.
+ */
+
+/**
+ * Migration Guide for Custom Storage Adapters
+ *
+ * If you have a custom storage adapter, you can add capabilities support in two ways:
+ *
+ * **Option 1: Static capabilities (recommended)**
+ * Add a static `capabilities` property to your class. EntityManager reads this via
+ * `storage.constructor.capabilities`. This is the preferred pattern for new code.
+ *
+ * ```js
+ * export class MyCustomStorage {
+ *   static capabilities = {
+ *     supportsTotal: true,
+ *     supportsFilters: true,
+ *     supportsPagination: true,
+ *     supportsCaching: true // set to false for in-memory storages
+ *   }
+ *
+ *   // Backward-compat instance getter (optional, for smooth migration)
+ *   get supportsCaching() {
+ *     return MyCustomStorage.capabilities.supportsCaching
+ *   }
+ *
+ *   async list(params) { ... }
+ *   async get(id) { ... }
+ *   // ... other methods
+ * }
+ * ```
+ *
+ * **Option 2: Instance property only (legacy)**
+ * Keep using instance properties. EntityManager's `isCacheEnabled` check uses:
+ * `if (storage?.supportsCaching === false) return false`
+ * This works with instance properties directly.
+ *
+ * ```js
+ * export class MyLegacyStorage {
+ *   supportsCaching = true // or false for in-memory
+ *
+ *   async list(params) { ... }
+ * }
+ * ```
+ *
+ * **No capabilities declared**
+ * If your storage doesn't declare capabilities, EntityManager will:
+ * - Assume `supportsTotal: false` (disables auto-caching threshold check)
+ * - Assume `supportsCaching: undefined` (caching allowed, but threshold check fails)
+ * - Gracefully degrade without errors
+ *
+ * Use `getStorageCapabilities(storage)` helper to read merged capabilities with defaults.
+ */
+
+/**
+ * Default capabilities for storages that don't declare their own.
+ * All capabilities default to false for safe degradation.
+ *
+ * @type {StorageCapabilities}
+ */
+export const DEFAULT_STORAGE_CAPABILITIES = {
+  supportsTotal: false,
+  supportsFilters: false,
+  supportsPagination: false,
+  supportsCaching: false
+}
+
+/**
+ * Read capabilities from a storage instance.
+ * Accesses static `capabilities` property via constructor with fallback to defaults.
+ *
+ * @param {object} storage - Storage adapter instance
+ * @returns {StorageCapabilities} Merged capabilities with defaults
+ *
+ * @example
+ * const caps = getStorageCapabilities(myStorage)
+ * if (caps.supportsTotal) {
+ *   // Storage provides accurate total count
+ * }
+ */
+export function getStorageCapabilities(storage) {
+  const declared = storage?.constructor?.capabilities || {}
+  return {
+    ...DEFAULT_STORAGE_CAPABILITIES,
+    ...declared
+  }
+}
+
 export { ApiStorage, createApiStorage } from './ApiStorage.js'
 export { LocalStorage, createLocalStorage } from './LocalStorage.js'
 export { MemoryStorage, createMemoryStorage } from './MemoryStorage.js'

package/src/index.js

@@ -38,6 +38,9 @@ export * from './hooks/index.js'
 // Core (extension helpers)
 export * from './core/index.js'
 
+// Query (MongoDB-like filtering)
+export * from './query/index.js'
+
 // Utils
 export * from './utils/index.js'
 

package/src/query/FilterQuery.js

@@ -0,0 +1,277 @@
+/**
+ * FilterQuery - Resolves dropdown options for filters
+ *
+ * Abstracts option resolution from two sources:
+ * - 'entity': fetch options from a related EntityManager
+ * - 'field': extract distinct values from parent manager's cached items
+ *
+ * Usage:
+ * ```js
+ * // Entity source - fetch from genres EntityManager
+ * const query = new FilterQuery({
+ *   source: 'entity',
+ *   entity: 'genres',
+ *   label: 'name',
+ *   value: 'id'
+ * })
+ *
+ * // Field source - extract unique status values
+ * const query = new FilterQuery({
+ *   source: 'field',
+ *   field: 'status'
+ * })
+ *
+ * // Get options (async)
+ * const options = await query.getOptions(orchestrator)
+ * // → [{ label: 'Rock', value: 1 }, { label: 'Jazz', value: 2 }]
+ * ```
+ */
+import { getNestedValue } from './QueryExecutor.js'
+
+const VALID_SOURCES = ['entity', 'field']
+
+/**
+ * Resolve a value from an item using a path or function
+ *
+ * @param {object} item - The item to extract value from
+ * @param {string|Function} resolver - Path string ('name', 'author.country') or function (item => value)
+ * @returns {*} The resolved value
+ */
+function resolveValue(item, resolver) {
+  if (typeof resolver === 'function') {
+    return resolver(item)
+  }
+
+  // Use shared getNestedValue for path resolution
+  return getNestedValue(resolver, item)
+}
+
+export class FilterQuery {
+  /**
+   * @param {object} options
+   * @param {'entity'|'field'} options.source - Source type for options
+   * @param {string} [options.entity] - Entity name (required if source='entity')
+   * @param {string} [options.field] - Field name to extract values from (required if source='field')
+   * @param {object} [options.parentManager] - Parent EntityManager (for field source, set by builder)
+   * @param {string|Function} [options.label='name'] - Label resolver (path or function)
+   * @param {string|Function} [options.value='id'] - Value resolver (path or function)
+   * @param {Function} [options.transform] - Post-processing function for options
+   * @param {Function} [options.toQuery] - Transform filter value to query object
+   */
+  constructor(options = {}) {
+    const {
+      source,
+      entity = null,
+      field = null,
+      parentManager = null,
+      label = 'name',
+      value = 'id',
+      transform = null,
+      toQuery = null
+    } = options
+
+    // Validate source type
+    if (!source || !VALID_SOURCES.includes(source)) {
+      throw new Error(
+        `FilterQuery: source must be one of: ${VALID_SOURCES.join(', ')}. Got: ${source}`
+      )
+    }
+
+    // Validate source-specific requirements
+    if (source === 'entity' && !entity) {
+      throw new Error('FilterQuery: entity is required when source is "entity"')
+    }
+
+    if (source === 'field' && !field) {
+      throw new Error('FilterQuery: field is required when source is "field"')
+    }
+
+    this.source = source
+    this.entity = entity
+    this.field = field
+    this.parentManager = parentManager
+    this.label = label
+    this.value = value
+    this.transform = transform
+    this.toQuery = toQuery
+
+    // Internal cache
+    this._options = null
+    this._signals = null
+    this._subscriptions = []  // Signal unsubscribe functions for cleanup
+  }
+
+  /**
+   * Set the parent manager (called by useListPageBuilder for field source)
+   *
+   * @param {EntityManager} manager
+   * @returns {FilterQuery} this for chaining
+   */
+  setParentManager(manager) {
+    this.parentManager = manager
+    return this
+  }
+
+  /**
+   * Set the SignalBus for cache invalidation
+   *
+   * For entity sources, subscribes to CRUD signals ({entity}:created, {entity}:updated,
+   * {entity}:deleted) to automatically invalidate cached options when the source
+   * entity changes.
+   *
+   * @param {SignalBus} signals
+   * @returns {FilterQuery} this for chaining
+   */
+  setSignals(signals) {
+    // Clean up existing subscriptions if any
+    this._cleanupSubscriptions()
+
+    this._signals = signals
+
+    // Subscribe to entity CRUD signals for cache invalidation
+    if (this.source === 'entity' && this.entity && signals) {
+      const actions = ['created', 'updated', 'deleted']
+      for (const action of actions) {
+        const signalName = `${this.entity}:${action}`
+        const unbind = signals.on(signalName, () => this.invalidate())
+        this._subscriptions.push(unbind)
+      }
+    }
+
+    return this
+  }
+
+  /**
+   * Cleanup signal subscriptions
+   * @private
+   */
+  _cleanupSubscriptions() {
+    for (const unbind of this._subscriptions) {
+      if (typeof unbind === 'function') {
+        unbind()
+      }
+    }
+    this._subscriptions = []
+  }
+
+  /**
+   * Dispose the FilterQuery, cleaning up signal subscriptions
+   *
+   * Call this when the FilterQuery is no longer needed to prevent memory leaks.
+   */
+  dispose() {
+    this._cleanupSubscriptions()
+    this._signals = null
+    this._options = null
+  }
+
+  /**
+   * Invalidate the cached options (forces refresh on next getOptions)
+   */
+  invalidate() {
+    this._options = null
+  }
+
+  /**
+   * Get options for dropdown
+   *
+   * @param {Orchestrator} [orchestrator] - Required for entity source
+   * @returns {Promise<Array<{label: string, value: *}>>}
+   */
+  async getOptions(orchestrator = null) {
+    // Return cached options if available
+    if (this._options !== null) {
+      return this._options
+    }
+
+    let items = []
+
+    if (this.source === 'entity') {
+      items = await this._fetchFromEntity(orchestrator)
+    } else if (this.source === 'field') {
+      items = this._extractFromField()
+    }
+
+    // Map items to { label, value } format
+    let options = items.map(item => ({
+      label: resolveValue(item, this.label),
+      value: resolveValue(item, this.value)
+    }))
+
+    // Apply transform if provided
+    if (typeof this.transform === 'function') {
+      options = this.transform(options)
+    }
+
+    // Cache the result
+    this._options = options
+
+    return options
+  }
+
+  /**
+   * Fetch items from entity manager
+   *
+   * @param {Orchestrator} orchestrator
+   * @returns {Promise<Array>}
+   * @private
+   */
+  async _fetchFromEntity(orchestrator) {
+    if (!orchestrator) {
+      throw new Error('FilterQuery: orchestrator is required for entity source')
+    }
+
+    const manager = orchestrator.get(this.entity)
+    if (!manager) {
+      throw new Error(`FilterQuery: entity "${this.entity}" not found in orchestrator`)
+    }
+
+    // Fetch all items (large page_size to get everything)
+    const result = await manager.list({ page_size: 1000 })
+    return result.items || []
+  }
+
+  /**
+   * Extract unique values from parent manager's cached items
+   *
+   * @returns {Array}
+   * @private
+   */
+  _extractFromField() {
+    if (!this.parentManager) {
+      throw new Error('FilterQuery: parentManager is required for field source')
+    }
+
+    // Get cached items from parent manager
+    const cachedItems = this.parentManager._cache || []
+
+    if (cachedItems.length === 0) {
+      return []
+    }
+
+    // Extract unique values from the field
+    const seen = new Set()
+    const items = []
+
+    for (const item of cachedItems) {
+      const fieldValue = resolveValue(item, this.field)
+      if (fieldValue == null) continue
+
+      // Create a unique key for deduplication
+      const key = typeof fieldValue === 'object' ? JSON.stringify(fieldValue) : fieldValue
+
+      if (!seen.has(key)) {
+        seen.add(key)
+        // For field source, the item IS the value (create a simple object)
+        items.push({
+          [this.field]: fieldValue,
+          // Also set 'name' and 'id' defaults for simple resolution
+          name: fieldValue,
+          id: fieldValue
+        })
+      }
+    }
+
+    return items
+  }
+}