@danielsimonjr/memory-mcp 0.48.0 → 9.8.2

package/dist/utils/entityUtils.d.ts

@@ -0,0 +1,354 @@
+/**
+ * Entity Utilities
+ *
+ * Consolidated module for entity-related utilities including:
+ * - Entity lookup and manipulation functions
+ * - Tag normalization and matching
+ * - Date parsing and validation
+ * - Entity filtering by various criteria
+ * - Path utilities and validation
+ *
+ * @module utils/entityUtils
+ */
+import type { Entity, KnowledgeGraph } from '../types/index.js';
+/**
+ * Finds an entity by name in the graph.
+ * Overloaded to provide type-safe returns based on throwIfNotFound parameter.
+ *
+ * @param graph - The knowledge graph to search
+ * @param name - The entity name to find
+ * @param throwIfNotFound - Whether to throw if entity doesn't exist (default: true)
+ * @returns The entity if found, null if not found and throwIfNotFound is false
+ * @throws EntityNotFoundError if entity not found and throwIfNotFound is true
+ */
+export declare function findEntityByName(graph: KnowledgeGraph, name: string, throwIfNotFound: true): Entity;
+export declare function findEntityByName(graph: KnowledgeGraph, name: string, throwIfNotFound: false): Entity | null;
+export declare function findEntityByName(graph: KnowledgeGraph, name: string, throwIfNotFound?: boolean): Entity | null;
+/**
+ * Finds multiple entities by name.
+ *
+ * @param graph - The knowledge graph to search
+ * @param names - Array of entity names to find
+ * @param throwIfAnyNotFound - Whether to throw if any entity doesn't exist (default: true)
+ * @returns Array of found entities (may be shorter than names if throwIfAnyNotFound is false)
+ * @throws EntityNotFoundError if any entity not found and throwIfAnyNotFound is true
+ */
+export declare function findEntitiesByNames(graph: KnowledgeGraph, names: string[], throwIfAnyNotFound?: boolean): Entity[];
+/**
+ * Checks if an entity exists in the graph.
+ *
+ * @param graph - The knowledge graph to search
+ * @param name - The entity name to check
+ * @returns true if entity exists, false otherwise
+ */
+export declare function entityExists(graph: KnowledgeGraph, name: string): boolean;
+/**
+ * Gets the index of an entity in the graph's entities array.
+ *
+ * @param graph - The knowledge graph to search
+ * @param name - The entity name to find
+ * @returns The index if found, -1 otherwise
+ */
+export declare function getEntityIndex(graph: KnowledgeGraph, name: string): number;
+/**
+ * Removes an entity from the graph by name.
+ * Mutates the graph's entities array in place.
+ *
+ * @param graph - The knowledge graph to modify
+ * @param name - The entity name to remove
+ * @returns true if entity was removed, false if not found
+ */
+export declare function removeEntityByName(graph: KnowledgeGraph, name: string): boolean;
+/**
+ * Gets all entity names as a Set for fast lookup.
+ *
+ * @param graph - The knowledge graph
+ * @returns Set of all entity names
+ */
+export declare function getEntityNameSet(graph: KnowledgeGraph): Set<string>;
+/**
+ * Groups entities by their type.
+ *
+ * @param entities - Array of entities to group
+ * @returns Map of entity type to array of entities
+ */
+export declare function groupEntitiesByType(entities: Entity[]): Map<string, Entity[]>;
+/**
+ * Updates the lastModified timestamp on an entity.
+ * Mutates the entity in place.
+ *
+ * @param entity - The entity to update
+ * @returns The updated entity (same reference)
+ */
+export declare function touchEntity(entity: Entity): Entity;
+/**
+ * Normalizes a single tag to lowercase and trimmed.
+ *
+ * @param tag - Tag to normalize
+ * @returns Normalized tag
+ */
+export declare function normalizeTag(tag: string): string;
+/**
+ * Normalizes an array of tags to lowercase.
+ * Handles undefined/null input gracefully.
+ *
+ * @param tags - Array of tags to normalize, or undefined
+ * @returns Normalized tags array, or empty array if input is undefined/null
+ */
+export declare function normalizeTags(tags: string[] | undefined | null): string[];
+/**
+ * Checks if an entity's tags include any of the specified search tags.
+ * Both inputs are normalized before comparison.
+ *
+ * @param entityTags - Tags on the entity (may be undefined)
+ * @param searchTags - Tags to search for (may be undefined)
+ * @returns true if any search tag matches any entity tag, false if no match or either is empty
+ */
+export declare function hasMatchingTag(entityTags: string[] | undefined, searchTags: string[] | undefined): boolean;
+/**
+ * Checks if entity tags include ALL of the specified required tags.
+ *
+ * @param entityTags - Tags on the entity (may be undefined)
+ * @param requiredTags - All tags that must be present
+ * @returns true if all required tags are present
+ */
+export declare function hasAllTags(entityTags: string[] | undefined, requiredTags: string[]): boolean;
+/**
+ * Filters entities by tag match.
+ * Returns all entities if searchTags is empty or undefined.
+ *
+ * @param entities - Array of entities with optional tags property
+ * @param searchTags - Tags to filter by
+ * @returns Filtered entities that have at least one matching tag
+ */
+export declare function filterByTags<T extends {
+    tags?: string[];
+}>(entities: T[], searchTags: string[] | undefined): T[];
+/**
+ * Adds new tags to an existing tag array, avoiding duplicates.
+ * All tags are normalized to lowercase.
+ *
+ * @param existingTags - Current tags (may be undefined)
+ * @param newTags - Tags to add
+ * @returns Combined tags array with no duplicates
+ */
+export declare function addUniqueTags(existingTags: string[] | undefined, newTags: string[]): string[];
+/**
+ * Removes specified tags from an existing tag array.
+ * Comparison is case-insensitive.
+ *
+ * @param existingTags - Current tags (may be undefined)
+ * @param tagsToRemove - Tags to remove
+ * @returns Tags array with specified tags removed
+ */
+export declare function removeTags(existingTags: string[] | undefined, tagsToRemove: string[]): string[];
+/**
+ * Check if a date falls within a specified range.
+ *
+ * @param date - ISO 8601 date string to check (may be undefined)
+ * @param start - Optional start date (inclusive)
+ * @param end - Optional end date (inclusive)
+ * @returns True if date is within range or no filters are set
+ *
+ * @example
+ * ```typescript
+ * isWithinDateRange('2024-06-15T00:00:00Z', '2024-01-01T00:00:00Z', '2024-12-31T23:59:59Z'); // true
+ * isWithinDateRange('2024-06-15T00:00:00Z', '2024-07-01T00:00:00Z'); // false
+ * isWithinDateRange(undefined); // true (no filters)
+ * isWithinDateRange(undefined, '2024-01-01T00:00:00Z'); // false (has filter but no date)
+ * ```
+ */
+export declare function isWithinDateRange(date: string | undefined, start?: string, end?: string): boolean;
+/**
+ * Parse and validate date range strings.
+ *
+ * @param startDate - Optional ISO 8601 start date
+ * @param endDate - Optional ISO 8601 end date
+ * @returns Parsed Date objects or null
+ */
+export declare function parseDateRange(startDate?: string, endDate?: string): {
+    start: Date | null;
+    end: Date | null;
+};
+/**
+ * Validate if a string is a valid ISO 8601 date.
+ *
+ * @param date - Date string to validate
+ * @returns True if valid ISO 8601 date
+ */
+export declare function isValidISODate(date: string): boolean;
+/**
+ * Get current timestamp in ISO 8601 format.
+ *
+ * @returns Current timestamp string
+ */
+export declare function getCurrentTimestamp(): string;
+/**
+ * Checks if an entity's importance is within the specified range.
+ * Entities without importance are treated as not matching if any filter is set.
+ *
+ * @param importance - The entity's importance value (may be undefined)
+ * @param minImportance - Minimum importance filter (inclusive)
+ * @param maxImportance - Maximum importance filter (inclusive)
+ * @returns true if importance is within range or no filters are set
+ *
+ * @example
+ * ```typescript
+ * // Check if entity passes importance filter
+ * if (isWithinImportanceRange(entity.importance, 5, 10)) {
+ *   // Entity has importance between 5 and 10
+ * }
+ * ```
+ */
+export declare function isWithinImportanceRange(importance: number | undefined, minImportance?: number, maxImportance?: number): boolean;
+/**
+ * Filters entities by importance range.
+ * Returns all entities if no importance filters are specified.
+ *
+ * @param entities - Array of entities to filter
+ * @param minImportance - Minimum importance filter (inclusive)
+ * @param maxImportance - Maximum importance filter (inclusive)
+ * @returns Filtered entities within the importance range
+ */
+export declare function filterByImportance(entities: Entity[], minImportance?: number, maxImportance?: number): Entity[];
+/**
+ * Filters entities by creation date range.
+ *
+ * @param entities - Array of entities to filter
+ * @param startDate - Start of date range (inclusive)
+ * @param endDate - End of date range (inclusive)
+ * @returns Filtered entities created within the date range
+ */
+export declare function filterByCreatedDate(entities: Entity[], startDate?: string, endDate?: string): Entity[];
+/**
+ * Filters entities by last modified date range.
+ *
+ * @param entities - Array of entities to filter
+ * @param startDate - Start of date range (inclusive)
+ * @param endDate - End of date range (inclusive)
+ * @returns Filtered entities modified within the date range
+ */
+export declare function filterByModifiedDate(entities: Entity[], startDate?: string, endDate?: string): Entity[];
+/**
+ * Filters entities by entity type.
+ *
+ * @param entities - Array of entities to filter
+ * @param entityType - Entity type to filter by (case-sensitive)
+ * @returns Filtered entities of the specified type
+ */
+export declare function filterByEntityType(entities: Entity[], entityType?: string): Entity[];
+/**
+ * Common search filters that can be applied to entities.
+ */
+export interface CommonSearchFilters {
+    tags?: string[];
+    minImportance?: number;
+    maxImportance?: number;
+    entityType?: string;
+    createdAfter?: string;
+    createdBefore?: string;
+    modifiedAfter?: string;
+    modifiedBefore?: string;
+}
+/**
+ * Checks if an entity passes all the specified filters.
+ * Short-circuits on first failing filter for performance.
+ *
+ * Note: Tag filtering should be handled separately using hasMatchingTag
+ * as it requires special normalization logic.
+ *
+ * @param entity - Entity to check
+ * @param filters - Filters to apply
+ * @returns true if entity passes all filters
+ */
+export declare function entityPassesFilters(entity: Entity, filters: Omit<CommonSearchFilters, 'tags'>): boolean;
+/**
+ * Sanitizes an object by removing potentially dangerous keys.
+ * This prevents prototype pollution attacks when using Object.assign() or spread operators.
+ *
+ * @param obj - The object to sanitize
+ * @returns A new object with dangerous keys removed
+ *
+ * @example
+ * ```typescript
+ * // Safe usage with Object.assign
+ * const updates = sanitizeObject(userInput);
+ * Object.assign(entity, updates);
+ *
+ * // Protects against prototype pollution
+ * const malicious = { __proto__: { admin: true } };
+ * const safe = sanitizeObject(malicious); // { }
+ * ```
+ */
+export declare function sanitizeObject<T extends Record<string, unknown>>(obj: T): Partial<T>;
+/**
+ * Escapes a CSV field to prevent formula injection attacks.
+ * Prepends a single quote to values that start with dangerous characters.
+ *
+ * @param field - The field value to escape
+ * @returns Escaped field value safe for CSV export
+ *
+ * @example
+ * ```typescript
+ * escapeCsvFormula('=SUM(A1:A10)'); // "'=SUM(A1:A10)"
+ * escapeCsvFormula('normal text'); // 'normal text'
+ * ```
+ */
+export declare function escapeCsvFormula(field: string | undefined | null): string;
+/**
+ * Validate and normalize a file path to prevent path traversal attacks.
+ *
+ * This function:
+ * - Normalizes the path to canonical form
+ * - Converts relative paths to absolute paths
+ * - Detects and prevents path traversal attempts (..)
+ *
+ * @param filePath - The file path to validate
+ * @param baseDir - Optional base directory for relative paths (defaults to process.cwd())
+ * @returns Validated absolute file path
+ * @throws {FileOperationError} If path traversal is detected or path is invalid
+ *
+ * @example
+ * ```typescript
+ * // Valid paths
+ * validateFilePath('/var/data/memory.jsonl'); // Returns absolute path
+ * validateFilePath('data/memory.jsonl'); // Returns absolute path from cwd
+ *
+ * // Invalid paths (throws FileOperationError)
+ * validateFilePath('../../../etc/passwd'); // Path traversal detected
+ * validateFilePath('/var/data/../../../etc/passwd'); // Path traversal detected
+ * ```
+ */
+export declare function validateFilePath(filePath: string, baseDir?: string): string;
+/**
+ * Default memory file path (in project root directory, outside dist/).
+ */
+export declare const defaultMemoryPath: string;
+/**
+ * Ensure memory file path with backward compatibility migration.
+ *
+ * Handles:
+ * 1. Custom MEMORY_FILE_PATH environment variable (with path traversal protection)
+ * 2. Backward compatibility: migrates memory.json to memory.jsonl
+ * 3. Absolute vs relative path resolution
+ *
+ * @returns Resolved and validated memory file path
+ * @throws {FileOperationError} If path traversal is detected in MEMORY_FILE_PATH
+ *
+ * @example
+ * ```typescript
+ * // Use environment variable
+ * process.env.MEMORY_FILE_PATH = '/data/memory.jsonl';
+ * const path = await ensureMemoryFilePath(); // '/data/memory.jsonl'
+ *
+ * // Use default path
+ * delete process.env.MEMORY_FILE_PATH;
+ * const path = await ensureMemoryFilePath(); // './memory.jsonl'
+ *
+ * // Invalid path (throws error)
+ * process.env.MEMORY_FILE_PATH = '../../../etc/passwd';
+ * await ensureMemoryFilePath(); // Throws FileOperationError
+ * ```
+ */
+export declare function ensureMemoryFilePath(): Promise<string>;
+//# sourceMappingURL=entityUtils.d.ts.map

package/dist/utils/entityUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityUtils.d.ts","sourceRoot":"","sources":["../../src/utils/entityUtils.ts"],"names":[],"mappings":"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"}