@danielsimonjr/memoryjs 1.0.0

package/dist/core/SQLiteStorage.d.ts

@@ -0,0 +1,354 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"version":3,"file":"SQLiteStorage.d.ts","sourceRoot":"","sources":["../../src/core/SQLiteStorage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAKhI;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,aAAa;IAyDrC,OAAO,CAAC,UAAU;IAxD9B;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAe;IAE5B;;OAEG;IACH,OAAO,CAAC,EAAE,CAA6B;IAEvC;;OAEG;IACH,OAAO,CAAC,WAAW,CAAkB;IAErC;;;OAGG;IACH,OAAO,CAAC,KAAK,CAA+B;IAE5C;;OAEG;IACH,OAAO,CAAC,SAAS,CAA8B;IAE/C;;OAEG;IACH,OAAO,CAAC,SAAS,CAA8B;IAE/C;;OAEG;IACH,OAAO,CAAC,cAAc,CAAyC;IAE/D;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAa;IAEnC;;;OAGG;IACH,OAAO,CAAC,0BAA0B,CAAsC;IAExE;;;;OAIG;gBACiB,UAAU,EAAE,MAAM;IAEtC;;OAEG;IACH,OAAO,CAAC,UAAU;IAmBlB;;OAEG;IACH,OAAO,CAAC,YAAY;IAkFpB;;OAEG;IACH,OAAO,CAAC,SAAS;IA2BjB;;OAEG;IACH,OAAO,CAAC,WAAW;IAanB;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAKlD;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,cAAc,CAAC;IAYpD;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnC;;;;OAIG;IACH,OAAO,CAAC,4BAA4B;IAIpC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAI/B;;;;;;;OAOG;IACG,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA+ErD;;;;;;;OAOG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCjD;;;;;;;OAOG;IACG,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAwCvD;;;;;;;;OAQG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAuDlF;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B;;OAEG;IACH,UAAU,IAAI,IAAI;IAgBlB;;;;;;;OAOG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIjD;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAY/C;;;;OAIG;IACH,cAAc,IAAI,MAAM,EAAE;IAI1B;;;;;OAKG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAM5D;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAqBrE;;;;;OAKG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAkB1C;;;;OAIG;IACH,WAAW,IAAI,MAAM;IAIrB;;;;OAIG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;;;;;;OAOG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,EAAE;IAqBhD;;;;;;;OAOG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,EAAE;IAqB9C;;;;;;;OAOG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,EAAE;IAiC/C;;;;;OAKG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAiBzC;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAiB7B;;;;;;OAMG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAkBzE;;;;;OAKG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAmBjD;;;;OAIG;IACG,iBAAiB,IAAI,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAkBxD;;;;OAIG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAYzC;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAW1B;;;;;OAKG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAazC;;;;OAIG;IACH,iBAAiB,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE;CAmBzD"}