@danielsimonjr/memoryjs 1.0.0 → 1.2.0

package/dist/core/GraphStorage.d.ts

@@ -1,395 +0,0 @@
-/**
- * Graph Storage
- *
- * Handles file I/O operations for the knowledge graph using JSONL format.
- * Implements IGraphStorage interface for storage abstraction.
- *
- * @module core/GraphStorage
- */
-import type { KnowledgeGraph, Entity, Relation, ReadonlyKnowledgeGraph, IGraphStorage, LowercaseData } from '../types/index.js';
-import { BatchTransaction } from './TransactionManager.js';
-import { GraphEventEmitter } from './GraphEventEmitter.js';
-/**
- * GraphStorage manages persistence of the knowledge graph to disk.
- *
- * Uses JSONL (JSON Lines) format where each line is a separate JSON object
- * representing either an entity or a relation.
- *
- * OPTIMIZED: Implements in-memory caching to avoid repeated disk reads.
- * Cache is invalidated on every write operation to ensure consistency.
- *
- * @example
- * ```typescript
- * const storage = new GraphStorage('/path/to/memory.jsonl');
- * const graph = await storage.loadGraph();
- * graph.entities.push(newEntity);
- * await storage.saveGraph(graph);
- * ```
- */
-export declare class GraphStorage implements IGraphStorage {
-    private memoryFilePath;
-    /**
-     * Mutex for thread-safe access to storage operations.
-     * Prevents concurrent writes from corrupting the file or cache.
-     */
-    private mutex;
-    /**
-     * In-memory cache of the knowledge graph.
-     * Null when cache is empty or invalidated.
-     */
-    private cache;
-    /**
-     * Number of pending append operations since last compaction.
-     * Used to trigger automatic compaction when threshold is reached.
-     */
-    private pendingAppends;
-    /**
-     * Dynamic threshold for automatic compaction.
-     *
-     * Returns the larger of 100 or 10% of the current entity count.
-     * This scales with graph size to avoid too-frequent compaction on large graphs
-     * while maintaining a reasonable minimum for small graphs.
-     *
-     * @returns Compaction threshold value
-     */
-    private get compactionThreshold();
-    /**
-     * O(1) entity lookup by name.
-     */
-    private nameIndex;
-    /**
-     * O(1) entity lookup by type.
-     */
-    private typeIndex;
-    /**
-     * Pre-computed lowercase strings for search optimization.
-     */
-    private lowercaseCache;
-    /**
-     * O(1) relation lookup by entity name.
-     */
-    private relationIndex;
-    /**
-     * O(1) observation word lookup by entity.
-     * Maps words in observations to entity names.
-     */
-    private observationIndex;
-    /**
-     * Phase 10 Sprint 2: Event emitter for graph change notifications.
-     * Allows external systems to subscribe to graph changes.
-     */
-    private eventEmitter;
-    /**
-     * Create a new GraphStorage instance.
-     *
-     * @param memoryFilePath - Absolute path to the JSONL file
-     */
-    constructor(memoryFilePath: string);
-    /**
-     * Get the event emitter for subscribing to graph changes.
-     *
-     * @returns GraphEventEmitter instance
-     *
-     * @example
-     * ```typescript
-     * const storage = new GraphStorage('/data/memory.jsonl');
-     *
-     * // Subscribe to entity creation events
-     * storage.events.on('entity:created', (event) => {
-     *   console.log(`Entity ${event.entity.name} created`);
-     * });
-     *
-     * // Subscribe to all events
-     * storage.events.onAny((event) => {
-     *   console.log(`Graph event: ${event.type}`);
-     * });
-     * ```
-     */
-    get events(): GraphEventEmitter;
-    /**
-     * Write content to file with fsync for durability.
-     *
-     * @param content - Content to write
-     */
-    private durableWriteFile;
-    /**
-     * Append content to file with fsync for durability.
-     *
-     * @param content - Content to append
-     * @param prependNewline - Whether to prepend a newline
-     */
-    private durableAppendFile;
-    /**
-     * Load the knowledge graph from disk (read-only access).
-     *
-     * OPTIMIZED: Returns cached reference directly without copying.
-     * This is O(1) regardless of graph size. For mutation operations,
-     * use getGraphForMutation() instead.
-     *
-     * @returns Promise resolving to read-only knowledge graph reference
-     * @throws Error if file exists but cannot be read or parsed
-     */
-    loadGraph(): Promise<ReadonlyKnowledgeGraph>;
-    /**
-     * Get a mutable copy of the graph for write operations.
-     *
-     * Creates deep copies of entity and relation arrays to allow
-     * safe mutation without affecting the cached data.
-     *
-     * @returns Promise resolving to mutable knowledge graph copy
-     */
-    getGraphForMutation(): Promise<KnowledgeGraph>;
-    /**
-     * Ensure the cache is loaded from disk.
-     *
-     * @returns Promise resolving when cache is populated
-     */
-    ensureLoaded(): Promise<void>;
-    /**
-     * Internal method to load graph from disk into cache.
-     */
-    private loadFromDisk;
-    /**
-     * Build all entity indexes from entity array.
-     */
-    private buildEntityIndexes;
-    /**
-     * Build relation index from relation array.
-     */
-    private buildRelationIndex;
-    /**
-     * Clear all indexes.
-     */
-    private clearIndexes;
-    /**
-     * Save the knowledge graph to disk.
-     *
-     * OPTIMIZED: Updates cache directly after write to avoid re-reading.
-     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
-     *
-     * Writes the graph to JSONL format, with one JSON object per line.
-     *
-     * @param graph - The knowledge graph to save
-     * @returns Promise resolving when save is complete
-     * @throws Error if file cannot be written
-     */
-    saveGraph(graph: KnowledgeGraph): Promise<void>;
-    /**
-     * Append a single entity to the file (O(1) write operation).
-     *
-     * OPTIMIZED: Uses file append instead of full rewrite.
-     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
-     * Updates cache in-place and triggers compaction when threshold is reached.
-     *
-     * @param entity - The entity to append
-     * @returns Promise resolving when append is complete
-     */
-    appendEntity(entity: Entity): Promise<void>;
-    /**
-     * Append a single relation to the file (O(1) write operation).
-     *
-     * OPTIMIZED: Uses file append instead of full rewrite.
-     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
-     * Updates cache in-place and triggers compaction when threshold is reached.
-     *
-     * @param relation - The relation to append
-     * @returns Promise resolving when append is complete
-     */
-    appendRelation(relation: Relation): Promise<void>;
-    /**
-     * Compact the file by rewriting it with only current cache contents.
-     *
-     * THREAD-SAFE: Uses mutex to prevent concurrent operations.
-     * Removes duplicate entries and cleans up the file.
-     * Resets pending appends counter.
-     *
-     * @returns Promise resolving when compaction is complete
-     */
-    compact(): Promise<void>;
-    /**
-     * Internal compact implementation (must be called within mutex).
-     *
-     * @returns Promise resolving when compaction is complete
-     */
-    private compactInternal;
-    /**
-     * Internal saveGraph implementation (must be called within mutex).
-     *
-     * @param graph - The knowledge graph to save
-     * @returns Promise resolving when save is complete
-     */
-    private saveGraphInternal;
-    /**
-     * Get the current pending appends count.
-     *
-     * Useful for testing compaction behavior.
-     *
-     * @returns Number of pending appends since last compaction
-     */
-    getPendingAppends(): number;
-    /**
-     * Update an entity in-place in the cache and append to file.
-     *
-     * OPTIMIZED: Modifies cache directly and appends updated version to file.
-     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
-     * Does not rewrite the entire file - compaction handles deduplication later.
-     *
-     * @param entityName - Name of the entity to update
-     * @param updates - Partial entity updates to apply
-     * @returns Promise resolving to true if entity was found and updated, false otherwise
-     */
-    updateEntity(entityName: string, updates: Partial<Entity>): Promise<boolean>;
-    /**
-     * Manually clear the cache.
-     *
-     * Useful for testing or when external processes modify the file.
-     *
-     * @returns void
-     */
-    clearCache(): void;
-    /**
-     * Get the file path being used for storage.
-     *
-     * @returns The memory file path
-     */
-    getFilePath(): string;
-    /**
-     * Get an entity by name in O(1) time.
-     *
-     * OPTIMIZED: Uses NameIndex for constant-time lookup.
-     *
-     * @param name - Entity name to look up
-     * @returns Entity if found, undefined otherwise
-     */
-    getEntityByName(name: string): Entity | undefined;
-    /**
-     * Check if an entity exists by name in O(1) time.
-     *
-     * @param name - Entity name to check
-     * @returns True if entity exists
-     */
-    hasEntity(name: string): boolean;
-    /**
-     * Get all entities of a given type in O(1) time.
-     *
-     * OPTIMIZED: Uses TypeIndex for constant-time lookup of entity names,
-     * then uses NameIndex for O(1) entity retrieval.
-     *
-     * @param entityType - Entity type to filter by (case-insensitive)
-     * @returns Array of entities with the given type
-     */
-    getEntitiesByType(entityType: string): Entity[];
-    /**
-     * Get pre-computed lowercase data for an entity.
-     *
-     * OPTIMIZED: Avoids repeated toLowerCase() calls during search.
-     *
-     * @param entityName - Entity name to get lowercase data for
-     * @returns LowercaseData if entity exists, undefined otherwise
-     */
-    getLowercased(entityName: string): LowercaseData | undefined;
-    /**
-     * Get all unique entity types in the graph.
-     *
-     * @returns Array of unique entity types (lowercase)
-     */
-    getEntityTypes(): string[];
-    /**
-     * Get all relations where the entity is the source (outgoing relations) in O(1) time.
-     *
-     * OPTIMIZED: Uses RelationIndex for constant-time lookup.
-     *
-     * @param entityName - Entity name to look up outgoing relations for
-     * @returns Array of relations where entity is the source
-     */
-    getRelationsFrom(entityName: string): Relation[];
-    /**
-     * Get all relations where the entity is the target (incoming relations) in O(1) time.
-     *
-     * OPTIMIZED: Uses RelationIndex for constant-time lookup.
-     *
-     * @param entityName - Entity name to look up incoming relations for
-     * @returns Array of relations where entity is the target
-     */
-    getRelationsTo(entityName: string): Relation[];
-    /**
-     * Get all relations involving the entity (both incoming and outgoing) in O(1) time.
-     *
-     * OPTIMIZED: Uses RelationIndex for constant-time lookup.
-     *
-     * @param entityName - Entity name to look up all relations for
-     * @returns Array of all relations involving the entity
-     */
-    getRelationsFor(entityName: string): Relation[];
-    /**
-     * Check if an entity has any relations.
-     *
-     * @param entityName - Entity name to check
-     * @returns True if entity has any relations
-     */
-    hasRelations(entityName: string): boolean;
-    /**
-     * Get entities that have observations containing the given word.
-     * Uses the observation index for O(1) lookup.
-     *
-     * OPTIMIZED: Uses ObservationIndex for constant-time lookup instead of
-     * linear scan through all entities and their observations.
-     *
-     * @param word - Word to search for in observations
-     * @returns Set of entity names
-     */
-    getEntitiesByObservationWord(word: string): Set<string>;
-    /**
-     * Get entities that have observations containing ANY of the given words (union).
-     * Uses the observation index for O(1) lookup per word.
-     *
-     * OPTIMIZED: Uses ObservationIndex for constant-time lookups.
-     *
-     * @param words - Array of words to search for
-     * @returns Set of entity names containing any of the words
-     */
-    getEntitiesByAnyObservationWord(words: string[]): Set<string>;
-    /**
-     * Get entities that have observations containing ALL of the given words (intersection).
-     * Uses the observation index for O(1) lookup per word.
-     *
-     * OPTIMIZED: Uses ObservationIndex for constant-time lookups and set intersection.
-     *
-     * @param words - Array of words that must all be present
-     * @returns Set of entity names containing all of the words
-     */
-    getEntitiesByAllObservationWords(words: string[]): Set<string>;
-    /**
-     * Get statistics about the observation index.
-     *
-     * @returns Object with wordCount and entityCount
-     */
-    getObservationIndexStats(): {
-        wordCount: number;
-        entityCount: number;
-    };
-    /**
-     * Create a new batch transaction for atomic operations.
-     *
-     * Returns a BatchTransaction instance that can be used to queue multiple
-     * operations and execute them atomically with a single save operation.
-     *
-     * @returns A new BatchTransaction instance
-     *
-     * @example
-     * ```typescript
-     * const storage = new GraphStorage('/data/memory.jsonl');
-     *
-     * // Create and execute a batch transaction
-     * const result = await storage.transaction()
-     *   .createEntity({ name: 'Alice', entityType: 'person', observations: ['Developer'] })
-     *   .createEntity({ name: 'Bob', entityType: 'person', observations: ['Designer'] })
-     *   .createRelation({ from: 'Alice', to: 'Bob', relationType: 'knows' })
-     *   .execute();
-     *
-     * console.log(`Batch completed: ${result.operationsExecuted} operations`);
-     * ```
-     */
-    transaction(): BatchTransaction;
-}
-//# sourceMappingURL=GraphStorage.d.ts.map

package/dist/core/GraphStorage.d.ts.map

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