@danielsimonjr/memoryjs 1.0.0 → 1.1.0

package/dist/core/SQLiteStorage.d.ts

@@ -1,354 +0,0 @@
-/**
- * SQLite Storage
- *
- * Handles storage operations for the knowledge graph using better-sqlite3 (native SQLite).
- * Implements IGraphStorage interface for storage abstraction.
- *
- * Benefits over sql.js (WASM):
- * - 3-10x faster than WASM-based SQLite
- * - Native FTS5 full-text search support
- * - ACID transactions with proper durability
- * - Concurrent read access support
- * - No memory overhead from WASM runtime
- * - Direct disk I/O (no manual export/import)
- *
- * Features:
- * - Built-in indexes for O(1) lookups
- * - Referential integrity with ON DELETE CASCADE
- * - FTS5 full-text search on entity names and observations
- *
- * @module core/SQLiteStorage
- */
-import type { KnowledgeGraph, Entity, Relation, ReadonlyKnowledgeGraph, IGraphStorage, LowercaseData } from '../types/index.js';
-/**
- * SQLiteStorage manages persistence of the knowledge graph using native SQLite.
- *
- * Uses better-sqlite3 for native SQLite bindings with full FTS5 support,
- * referential integrity, and proper ACID transactions.
- *
- * @example
- * ```typescript
- * const storage = new SQLiteStorage('/path/to/memory.db');
- * await storage.ensureLoaded();
- * const graph = await storage.loadGraph();
- * ```
- */
-export declare class SQLiteStorage implements IGraphStorage {
-    private dbFilePath;
-    /**
-     * Mutex for thread-safe access to storage operations.
-     * Prevents concurrent writes from corrupting the cache.
-     * Note: SQLite itself handles file-level locking, but we need
-     * to protect our in-memory cache and index operations.
-     */
-    private mutex;
-    /**
-     * SQLite database instance.
-     */
-    private db;
-    /**
-     * Whether the database has been initialized.
-     */
-    private initialized;
-    /**
-     * In-memory cache for fast read operations.
-     * Synchronized with SQLite on writes.
-     */
-    private cache;
-    /**
-     * O(1) entity lookup by name.
-     */
-    private nameIndex;
-    /**
-     * O(1) entity lookup by type.
-     */
-    private typeIndex;
-    /**
-     * Pre-computed lowercase data for search optimization.
-     */
-    private lowercaseCache;
-    /**
-     * Pending changes counter for batching disk writes.
-     * Note: better-sqlite3 writes to disk immediately, but we track for API compatibility.
-     */
-    private pendingChanges;
-    /**
-     * Phase 4 Sprint 1: Bidirectional relation cache for O(1) repeated lookups.
-     * Maps entity name -> all relations involving that entity (both incoming and outgoing).
-     */
-    private bidirectionalRelationCache;
-    /**
-     * Create a new SQLiteStorage instance.
-     *
-     * @param dbFilePath - Absolute path to the SQLite database file
-     */
-    constructor(dbFilePath: string);
-    /**
-     * Initialize the database connection and schema.
-     */
-    private initialize;
-    /**
-     * Create database tables, indexes, and FTS5 virtual table.
-     */
-    private createTables;
-    /**
-     * Load all data from SQLite into memory cache.
-     */
-    private loadCache;
-    /**
-     * Convert a database row to an Entity object.
-     */
-    private rowToEntity;
-    /**
-     * Convert a database row to a Relation object.
-     */
-    private rowToRelation;
-    /**
-     * Update lowercase cache for an entity.
-     */
-    private updateLowercaseCache;
-    /**
-     * Load the knowledge graph (read-only access).
-     *
-     * @returns Promise resolving to read-only knowledge graph reference
-     */
-    loadGraph(): Promise<ReadonlyKnowledgeGraph>;
-    /**
-     * Get a mutable copy of the graph for write operations.
-     *
-     * @returns Promise resolving to mutable knowledge graph copy
-     */
-    getGraphForMutation(): Promise<KnowledgeGraph>;
-    /**
-     * Ensure the storage is loaded/initialized.
-     *
-     * @returns Promise resolving when ready
-     */
-    ensureLoaded(): Promise<void>;
-    /**
-     * Phase 4 Sprint 1: Invalidate bidirectional relation cache for an entity.
-     *
-     * @param entityName - Entity name to invalidate cache for
-     */
-    private invalidateBidirectionalCache;
-    /**
-     * Phase 4 Sprint 1: Clear the entire bidirectional relation cache.
-     */
-    private clearBidirectionalCache;
-    /**
-     * Save the entire knowledge graph to storage.
-     *
-     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
-     *
-     * @param graph - The knowledge graph to save
-     * @returns Promise resolving when save is complete
-     */
-    saveGraph(graph: KnowledgeGraph): Promise<void>;
-    /**
-     * Append a single entity to storage.
-     *
-     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
-     *
-     * @param entity - The entity to append
-     * @returns Promise resolving when append is complete
-     */
-    appendEntity(entity: Entity): Promise<void>;
-    /**
-     * Append a single relation to storage.
-     *
-     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
-     *
-     * @param relation - The relation to append
-     * @returns Promise resolving when append is complete
-     */
-    appendRelation(relation: Relation): Promise<void>;
-    /**
-     * Update an entity in storage.
-     *
-     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
-     *
-     * @param entityName - Name of the entity to update
-     * @param updates - Partial entity updates to apply
-     * @returns Promise resolving to true if found and updated
-     */
-    updateEntity(entityName: string, updates: Partial<Entity>): Promise<boolean>;
-    /**
-     * Compact the storage (runs VACUUM to reclaim space).
-     *
-     * THREAD-SAFE: Uses mutex to prevent concurrent operations.
-     *
-     * @returns Promise resolving when compaction is complete
-     */
-    compact(): Promise<void>;
-    /**
-     * Clear any in-memory cache.
-     */
-    clearCache(): void;
-    /**
-     * 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 all unique entity types in the graph.
-     *
-     * @returns Array of unique entity types (lowercase)
-     */
-    getEntityTypes(): string[];
-    /**
-     * Get pre-computed lowercase data for an entity.
-     *
-     * @param entityName - Entity name to get lowercase data for
-     * @returns LowercaseData if entity exists, undefined otherwise
-     */
-    getLowercased(entityName: string): LowercaseData | undefined;
-    /**
-     * Perform full-text search using FTS5.
-     *
-     * @param query - Search query (supports FTS5 query syntax)
-     * @returns Array of matching entity names with relevance scores
-     */
-    fullTextSearch(query: string): Array<{
-        name: string;
-        score: number;
-    }>;
-    /**
-     * Perform a simple text search (LIKE-based, case-insensitive).
-     *
-     * @param searchTerm - Term to search for
-     * @returns Array of matching entity names
-     */
-    simpleSearch(searchTerm: string): string[];
-    /**
-     * Get the storage path/location.
-     *
-     * @returns The storage path
-     */
-    getFilePath(): string;
-    /**
-     * Get the current pending changes count.
-     *
-     * @returns Number of pending changes since last reset
-     */
-    getPendingAppends(): number;
-    /**
-     * Force persistence to disk (no-op for better-sqlite3 as it writes immediately).
-     *
-     * @returns Promise resolving when persistence is complete
-     */
-    flush(): Promise<void>;
-    /**
-     * Close the database connection.
-     */
-    close(): void;
-    /**
-     * Get all relations where the entity is the source (outgoing relations).
-     *
-     * OPTIMIZED: Uses SQLite index on fromEntity for O(log n) 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).
-     *
-     * OPTIMIZED: Uses SQLite index on toEntity for O(log n) 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).
-     *
-     * OPTIMIZED: Phase 4 Sprint 1 - Uses bidirectional cache for O(1) repeated lookups.
-     *
-     * @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;
-    /**
-     * Phase 4 Sprint 11: Ensure embeddings table exists.
-     *
-     * Creates the embeddings table if it doesn't exist.
-     * Separate table from entities to avoid schema migration complexity.
-     */
-    private ensureEmbeddingsTable;
-    /**
-     * Phase 4 Sprint 11: Store an embedding for an entity.
-     *
-     * @param entityName - Name of the entity
-     * @param vector - Embedding vector
-     * @param model - Model name used for the embedding
-     */
-    storeEmbedding(entityName: string, vector: number[], model: string): void;
-    /**
-     * Phase 4 Sprint 11: Get an embedding for an entity.
-     *
-     * @param entityName - Name of the entity
-     * @returns Embedding vector if found, null otherwise
-     */
-    getEmbedding(entityName: string): number[] | null;
-    /**
-     * Phase 4 Sprint 11: Load all embeddings from storage.
-     *
-     * @returns Array of [entityName, vector] pairs
-     */
-    loadAllEmbeddings(): Promise<[string, number[]][]>;
-    /**
-     * Phase 4 Sprint 11: Remove an embedding for an entity.
-     *
-     * @param entityName - Name of the entity
-     */
-    removeEmbedding(entityName: string): void;
-    /**
-     * Phase 4 Sprint 11: Clear all embeddings from storage.
-     */
-    clearAllEmbeddings(): void;
-    /**
-     * Phase 4 Sprint 11: Check if an entity has an embedding.
-     *
-     * @param entityName - Name of the entity
-     * @returns True if embedding exists
-     */
-    hasEmbedding(entityName: string): boolean;
-    /**
-     * Phase 4 Sprint 11: Get embedding statistics.
-     *
-     * @returns Stats about stored embeddings
-     */
-    getEmbeddingStats(): {
-        count: number;
-        models: string[];
-    };
-}
-//# sourceMappingURL=SQLiteStorage.d.ts.map

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

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