@dollhousemcp/mcp-server/dist/services/query/FilterService.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * FilterService - Element filtering implementation
 *
 * Provides stateless filtering capabilities for element arrays based on
 * metadata and other criteria. All filters combine with AND logic except
 * tagsAny which uses OR logic.
 *
 * SECURITY:
 * - All string inputs are sanitized using normalizeSearchTerm
 * - Date inputs are validated as ISO 8601 format
 * - Tag arrays are validated and limited
 * - Missing metadata fields are handled gracefully
 * - Validation failures are logged to SecurityMonitor
 *
 * @see src/services/query/types.ts for interface definitions
 */
import { IElement } from '../../types/elements/IElement.js';
import { FilterCriteria, AppliedFilters, IFilterService } from './types.js';
/**
 * FilterService implementation
 *
 * Stateless service for filtering element arrays. Safe for injection
 * via DI and concurrent use across multiple operations.
 *
 * @template T - Element type being filtered (must extend IElement)
 */
export declare class FilterService<T extends IElement = IElement> implements IFilterService<T> {
    /**
     * Filter an array of elements based on criteria
     *
     * All criteria are optional and combined with AND logic when multiple
     * filters are specified. The exception is tagsAny which uses OR logic
     * (element must have ANY of the specified tags).
     *
     * Elements with missing metadata fields pass the filter if that field
     * is not required by the criteria (graceful degradation).
     *
     * @param items - Array of elements to filter
     * @param criteria - Filter criteria to apply
     * @returns Filtered array (may be empty if no matches)
     * @throws {Error} If filter criteria contain invalid values
     *
     * @example
     * ```typescript
     * const filtered = filterService.filter(elements, {
     *   nameContains: 'code review',
     *   tags: ['typescript', 'linting'],
     *   status: 'active'
     * });
     * ```
     */
    filter(items: T[], criteria?: FilterCriteria): T[];
    /**
     * Build a summary of which filters will be applied
     *
     * Useful for logging and debugging query execution.
     * Returns a sanitized copy of the criteria with count.
     *
     * @param criteria - Filter criteria
     * @returns Summary of applicable filters
     *
     * @example
     * ```typescript
     * const summary = filterService.summarizeFilters(criteria);
     * logger.debug('Applying filters', summary);
     * ```
     */
    summarizeFilters(criteria?: FilterCriteria): AppliedFilters;
    /**
     * Validate filter criteria without applying them
     *
     * Checks all criteria for:
     * - Valid string lengths
     * - Valid date formats
     * - Valid tag arrays
     * - Valid status values
     *
     * Logs security events for validation failures.
     *
     * @param criteria - Filter criteria to validate
     * @returns True if criteria are valid
     * @throws {Error} If criteria are invalid with descriptive message
     *
     * @example
     * ```typescript
     * try {
     *   filterService.validateCriteria(userInput);
     * } catch (error) {
     *   logger.error('Invalid filter criteria', error);
     * }
     * ```
     */
    validateCriteria(criteria?: FilterCriteria): boolean;
    /**
     * Filter elements by name (case-insensitive partial match)
     */
    private filterByName;
    /**
     * Filter elements by tags (AND logic - must have ALL tags)
     */
    private filterByTags;
    /**
     * Filter elements by tags (OR logic - must have ANY tag)
     */
    private filterByTagsAny;
    /**
     * Filter elements by author (exact match, case-insensitive)
     */
    private filterByAuthor;
    /**
     * Filter elements created after a date (inclusive)
     */
    private filterByCreatedAfter;
    /**
     * Filter elements created before a date (inclusive)
     */
    private filterByCreatedBefore;
    /**
     * Filter elements by status
     */
    private filterByStatus;
    /**
     * Filter elements by description (case-insensitive substring match)
     */
    private filterByDescription;
    /**
     * Filter elements by category (case-insensitive exact match)
     */
    private filterByCategory;
    /**
     * Safely access an arbitrary metadata field that may not be on the IElementMetadata interface.
     * Used for extension fields like 'category' that exist on some elements.
     * Checks metadata.custom first (standard extensibility), then metadata directly
     * using property descriptor access to avoid unsafe type assertions.
     */
    private getMetadataField;
    /**
     * Validate a tag array
     */
    private validateTagArray;
    /**
     * Validate ISO 8601 date string
     */
    private validateISO8601Date;
    /**
     * Sanitize criteria for logging (remove potentially sensitive data)
     */
    private sanitizeCriteriaForLogging;
}
//# sourceMappingURL=FilterService.d.ts.map