@dollhousemcp/mcp-server
Version:
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.
133 lines • 4.44 kB
TypeScript
/**
* SortService - Element-agnostic sorting service
*
* Provides stable, secure sorting for any element type with support for:
* - Multiple sortable fields (name, created, modified, version, retention)
* - Ascending and descending order
* - Semantic version comparison
* - ISO 8601 date comparison
* - Null-safe handling (sorts nulls last)
* - Immutability (does not mutate input array)
*
* SECURITY NOTES:
* - All sortBy values validated against SortableField enum
* - No arbitrary field access allowed
* - Stable sort prevents timing attacks
* - Input validation prevents injection
*
* @module SortService
*/
import { IElement } from '../../types/elements/IElement.js';
import { SortOptions, AppliedSorting, ISortService } from './types.js';
/**
* Service for sorting arrays of elements
*
* Implements ISortService with support for multiple sort fields and stable ordering.
* Designed to be stateless and injectable via dependency injection.
*
* @template T - Element type extending IElement
*/
export declare class SortService<T extends IElement = IElement> implements ISortService<T> {
private static readonly DEFAULT_SORT_BY;
private static readonly DEFAULT_SORT_ORDER;
private static readonly VALID_SORT_FIELDS;
/**
* Sort an array of elements according to the specified options
*
* IMPLEMENTATION NOTES:
* - Does NOT mutate the input array (creates a shallow copy)
* - Maintains stable sort order (items with equal values retain original order)
* - Handles missing values by sorting them last
* - Validates sortBy field against allowed enum values
*
* @param items - Array of elements to sort
* @param options - Sorting configuration
* @returns New sorted array
* @throws {Error} If sort options are invalid
*/
sort(items: T[], options?: SortOptions): T[];
/**
* Get the default sorting configuration
*
* @returns Default sort options
*/
getDefaultSorting(): AppliedSorting;
/**
* Validate sort options without applying them
*
* SECURITY: Validates sortBy against enum to prevent arbitrary field access
*
* @param options - Sort options to validate
* @returns True if options are valid
* @throws {Error} If options are invalid
*/
validateOptions(options?: SortOptions): boolean;
/**
* Compare two elements for sorting
*
* IMPLEMENTATION NOTES:
* - Returns negative if a < b, positive if a > b, zero if equal
* - Handles null/undefined values by sorting them last
* - Uses field-specific comparison logic
* - Maintains stable sort (returns 0 for equal values)
*
* @param a - First element
* @param b - Second element
* @param field - Field to compare
* @returns Comparison result (-1, 0, 1)
*/
private compareElements;
/**
* Compare two strings case-insensitively
*
* Uses localeCompare for proper Unicode handling and stable ordering.
*
* @param a - First string
* @param b - Second string
* @returns Comparison result
*/
private compareStrings;
/**
* Compare two ISO 8601 date strings as timestamps
*
* Converts to Date objects and compares numerically.
* Invalid dates are treated as undefined (sorted last).
*
* @param a - First date string
* @param b - Second date string
* @returns Comparison result
*/
private compareDates;
/**
* Compare two semantic version strings (x.y.z format)
*
* Compares major, minor, and patch versions numerically.
* Invalid versions are sorted using string comparison.
*
* @param a - First version string
* @param b - Second version string
* @returns Comparison result
*/
private compareVersions;
/**
* Parse a semantic version string into components
*
* Handles formats like "1.0.0", "2.5.3", etc.
* Returns null for invalid versions.
*
* @param version - Version string to parse
* @returns Parsed version components or null
*/
private parseVersion;
/**
* Compare two numbers
*
* Handles NaN by treating as undefined (sorted last).
*
* @param a - First number
* @param b - Second number
* @returns Comparison result
*/
private compareNumbers;
}
//# sourceMappingURL=SortService.d.ts.map