@danielsimonjr/memory-mcp 12.2.3 → 12.5.2

package/dist/utils/entityUtils.d.ts

@@ -1,321 +0,0 @@
-/**
- * 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;
-/**
- * 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 same directory as compiled code).
- */
-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

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