@danielsimonjr/memory-mcp 0.48.0 → 9.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (209) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +2000 -194
  3. package/dist/__tests__/file-path.test.js +7 -11
  4. package/dist/__tests__/knowledge-graph.test.js +3 -8
  5. package/dist/core/EntityManager.d.ts +266 -0
  6. package/dist/core/EntityManager.d.ts.map +1 -0
  7. package/dist/core/EntityManager.js +85 -133
  8. package/dist/core/GraphEventEmitter.d.ts +202 -0
  9. package/dist/core/GraphEventEmitter.d.ts.map +1 -0
  10. package/dist/core/GraphEventEmitter.js +346 -0
  11. package/dist/core/GraphStorage.d.ts +395 -0
  12. package/dist/core/GraphStorage.d.ts.map +1 -0
  13. package/dist/core/GraphStorage.js +643 -31
  14. package/dist/core/GraphTraversal.d.ts +141 -0
  15. package/dist/core/GraphTraversal.d.ts.map +1 -0
  16. package/dist/core/GraphTraversal.js +573 -0
  17. package/dist/core/HierarchyManager.d.ts +111 -0
  18. package/dist/core/HierarchyManager.d.ts.map +1 -0
  19. package/dist/{features → core}/HierarchyManager.js +14 -9
  20. package/dist/core/ManagerContext.d.ts +72 -0
  21. package/dist/core/ManagerContext.d.ts.map +1 -0
  22. package/dist/core/ManagerContext.js +118 -0
  23. package/dist/core/ObservationManager.d.ts +85 -0
  24. package/dist/core/ObservationManager.d.ts.map +1 -0
  25. package/dist/core/ObservationManager.js +51 -57
  26. package/dist/core/RelationManager.d.ts +131 -0
  27. package/dist/core/RelationManager.d.ts.map +1 -0
  28. package/dist/core/RelationManager.js +31 -7
  29. package/dist/core/SQLiteStorage.d.ts +354 -0
  30. package/dist/core/SQLiteStorage.d.ts.map +1 -0
  31. package/dist/core/SQLiteStorage.js +917 -0
  32. package/dist/core/StorageFactory.d.ts +45 -0
  33. package/dist/core/StorageFactory.d.ts.map +1 -0
  34. package/dist/core/StorageFactory.js +64 -0
  35. package/dist/core/TransactionManager.d.ts +464 -0
  36. package/dist/core/TransactionManager.d.ts.map +1 -0
  37. package/dist/core/TransactionManager.js +490 -13
  38. package/dist/core/index.d.ts +17 -0
  39. package/dist/core/index.d.ts.map +1 -0
  40. package/dist/core/index.js +12 -2
  41. package/dist/features/AnalyticsManager.d.ts +44 -0
  42. package/dist/features/AnalyticsManager.d.ts.map +1 -0
  43. package/dist/features/AnalyticsManager.js +3 -2
  44. package/dist/features/ArchiveManager.d.ts +133 -0
  45. package/dist/features/ArchiveManager.d.ts.map +1 -0
  46. package/dist/features/ArchiveManager.js +221 -14
  47. package/dist/features/CompressionManager.d.ts +117 -0
  48. package/dist/features/CompressionManager.d.ts.map +1 -0
  49. package/dist/features/CompressionManager.js +189 -20
  50. package/dist/features/IOManager.d.ts +225 -0
  51. package/dist/features/IOManager.d.ts.map +1 -0
  52. package/dist/features/IOManager.js +1041 -0
  53. package/dist/features/StreamingExporter.d.ts +123 -0
  54. package/dist/features/StreamingExporter.d.ts.map +1 -0
  55. package/dist/features/StreamingExporter.js +203 -0
  56. package/dist/features/TagManager.d.ts +147 -0
  57. package/dist/features/TagManager.d.ts.map +1 -0
  58. package/dist/features/index.d.ts +12 -0
  59. package/dist/features/index.d.ts.map +1 -0
  60. package/dist/features/index.js +5 -6
  61. package/dist/index.d.ts +9 -0
  62. package/dist/index.d.ts.map +1 -0
  63. package/dist/index.js +10 -10
  64. package/dist/memory.jsonl +1 -26
  65. package/dist/search/BasicSearch.d.ts +51 -0
  66. package/dist/search/BasicSearch.d.ts.map +1 -0
  67. package/dist/search/BasicSearch.js +9 -3
  68. package/dist/search/BooleanSearch.d.ts +98 -0
  69. package/dist/search/BooleanSearch.d.ts.map +1 -0
  70. package/dist/search/BooleanSearch.js +156 -9
  71. package/dist/search/EmbeddingService.d.ts +178 -0
  72. package/dist/search/EmbeddingService.d.ts.map +1 -0
  73. package/dist/search/EmbeddingService.js +358 -0
  74. package/dist/search/FuzzySearch.d.ts +118 -0
  75. package/dist/search/FuzzySearch.d.ts.map +1 -0
  76. package/dist/search/FuzzySearch.js +241 -25
  77. package/dist/search/QueryCostEstimator.d.ts +111 -0
  78. package/dist/search/QueryCostEstimator.d.ts.map +1 -0
  79. package/dist/search/QueryCostEstimator.js +355 -0
  80. package/dist/search/RankedSearch.d.ts +71 -0
  81. package/dist/search/RankedSearch.d.ts.map +1 -0
  82. package/dist/search/RankedSearch.js +54 -6
  83. package/dist/search/SavedSearchManager.d.ts +79 -0
  84. package/dist/search/SavedSearchManager.d.ts.map +1 -0
  85. package/dist/search/SearchFilterChain.d.ts +120 -0
  86. package/dist/search/SearchFilterChain.d.ts.map +1 -0
  87. package/dist/search/SearchFilterChain.js +2 -4
  88. package/dist/search/SearchManager.d.ts +326 -0
  89. package/dist/search/SearchManager.d.ts.map +1 -0
  90. package/dist/search/SearchManager.js +148 -0
  91. package/dist/search/SearchSuggestions.d.ts +27 -0
  92. package/dist/search/SearchSuggestions.d.ts.map +1 -0
  93. package/dist/search/SearchSuggestions.js +1 -1
  94. package/dist/search/SemanticSearch.d.ts +149 -0
  95. package/dist/search/SemanticSearch.d.ts.map +1 -0
  96. package/dist/search/SemanticSearch.js +323 -0
  97. package/dist/search/TFIDFEventSync.d.ts +85 -0
  98. package/dist/search/TFIDFEventSync.d.ts.map +1 -0
  99. package/dist/search/TFIDFEventSync.js +133 -0
  100. package/dist/search/TFIDFIndexManager.d.ts +151 -0
  101. package/dist/search/TFIDFIndexManager.d.ts.map +1 -0
  102. package/dist/search/TFIDFIndexManager.js +232 -17
  103. package/dist/search/VectorStore.d.ts +235 -0
  104. package/dist/search/VectorStore.d.ts.map +1 -0
  105. package/dist/search/VectorStore.js +311 -0
  106. package/dist/search/index.d.ts +21 -0
  107. package/dist/search/index.d.ts.map +1 -0
  108. package/dist/search/index.js +12 -0
  109. package/dist/server/MCPServer.d.ts +21 -0
  110. package/dist/server/MCPServer.d.ts.map +1 -0
  111. package/dist/server/MCPServer.js +4 -4
  112. package/dist/server/responseCompressor.d.ts +94 -0
  113. package/dist/server/responseCompressor.d.ts.map +1 -0
  114. package/dist/server/responseCompressor.js +127 -0
  115. package/dist/server/toolDefinitions.d.ts +27 -0
  116. package/dist/server/toolDefinitions.d.ts.map +1 -0
  117. package/dist/server/toolDefinitions.js +188 -17
  118. package/dist/server/toolHandlers.d.ts +41 -0
  119. package/dist/server/toolHandlers.d.ts.map +1 -0
  120. package/dist/server/toolHandlers.js +467 -75
  121. package/dist/types/index.d.ts +13 -0
  122. package/dist/types/index.d.ts.map +1 -0
  123. package/dist/types/index.js +1 -1
  124. package/dist/types/types.d.ts +1654 -0
  125. package/dist/types/types.d.ts.map +1 -0
  126. package/dist/types/types.js +9 -0
  127. package/dist/utils/compressedCache.d.ts +192 -0
  128. package/dist/utils/compressedCache.d.ts.map +1 -0
  129. package/dist/utils/compressedCache.js +309 -0
  130. package/dist/utils/compressionUtil.d.ts +214 -0
  131. package/dist/utils/compressionUtil.d.ts.map +1 -0
  132. package/dist/utils/compressionUtil.js +247 -0
  133. package/dist/utils/constants.d.ts +245 -0
  134. package/dist/utils/constants.d.ts.map +1 -0
  135. package/dist/utils/constants.js +124 -0
  136. package/dist/utils/entityUtils.d.ts +321 -0
  137. package/dist/utils/entityUtils.d.ts.map +1 -0
  138. package/dist/utils/entityUtils.js +434 -4
  139. package/dist/utils/errors.d.ts +95 -0
  140. package/dist/utils/errors.d.ts.map +1 -0
  141. package/dist/utils/errors.js +24 -0
  142. package/dist/utils/formatters.d.ts +145 -0
  143. package/dist/utils/formatters.d.ts.map +1 -0
  144. package/dist/utils/{paginationUtils.js → formatters.js} +54 -3
  145. package/dist/utils/index.d.ts +23 -0
  146. package/dist/utils/index.d.ts.map +1 -0
  147. package/dist/utils/index.js +69 -31
  148. package/dist/utils/indexes.d.ts +270 -0
  149. package/dist/utils/indexes.d.ts.map +1 -0
  150. package/dist/utils/indexes.js +526 -0
  151. package/dist/utils/logger.d.ts +24 -0
  152. package/dist/utils/logger.d.ts.map +1 -0
  153. package/dist/utils/operationUtils.d.ts +124 -0
  154. package/dist/utils/operationUtils.d.ts.map +1 -0
  155. package/dist/utils/operationUtils.js +175 -0
  156. package/dist/utils/parallelUtils.d.ts +72 -0
  157. package/dist/utils/parallelUtils.d.ts.map +1 -0
  158. package/dist/utils/parallelUtils.js +169 -0
  159. package/dist/utils/schemas.d.ts +374 -0
  160. package/dist/utils/schemas.d.ts.map +1 -0
  161. package/dist/utils/schemas.js +302 -2
  162. package/dist/utils/searchAlgorithms.d.ts +99 -0
  163. package/dist/utils/searchAlgorithms.d.ts.map +1 -0
  164. package/dist/utils/searchAlgorithms.js +167 -0
  165. package/dist/utils/searchCache.d.ts +108 -0
  166. package/dist/utils/searchCache.d.ts.map +1 -0
  167. package/dist/utils/taskScheduler.d.ts +290 -0
  168. package/dist/utils/taskScheduler.d.ts.map +1 -0
  169. package/dist/utils/taskScheduler.js +466 -0
  170. package/dist/workers/index.d.ts +12 -0
  171. package/dist/workers/index.d.ts.map +1 -0
  172. package/dist/workers/index.js +9 -0
  173. package/dist/workers/levenshteinWorker.d.ts +60 -0
  174. package/dist/workers/levenshteinWorker.d.ts.map +1 -0
  175. package/dist/workers/levenshteinWorker.js +98 -0
  176. package/package.json +17 -4
  177. package/dist/__tests__/edge-cases/edge-cases.test.js +0 -406
  178. package/dist/__tests__/integration/workflows.test.js +0 -449
  179. package/dist/__tests__/performance/benchmarks.test.js +0 -413
  180. package/dist/__tests__/unit/core/EntityManager.test.js +0 -334
  181. package/dist/__tests__/unit/core/GraphStorage.test.js +0 -205
  182. package/dist/__tests__/unit/core/RelationManager.test.js +0 -274
  183. package/dist/__tests__/unit/features/CompressionManager.test.js +0 -350
  184. package/dist/__tests__/unit/search/BasicSearch.test.js +0 -311
  185. package/dist/__tests__/unit/search/BooleanSearch.test.js +0 -432
  186. package/dist/__tests__/unit/search/FuzzySearch.test.js +0 -448
  187. package/dist/__tests__/unit/search/RankedSearch.test.js +0 -379
  188. package/dist/__tests__/unit/utils/levenshtein.test.js +0 -77
  189. package/dist/core/KnowledgeGraphManager.js +0 -423
  190. package/dist/features/BackupManager.js +0 -311
  191. package/dist/features/ExportManager.js +0 -305
  192. package/dist/features/ImportExportManager.js +0 -50
  193. package/dist/features/ImportManager.js +0 -328
  194. package/dist/memory-saved-searches.jsonl +0 -0
  195. package/dist/memory-tag-aliases.jsonl +0 -0
  196. package/dist/types/analytics.types.js +0 -6
  197. package/dist/types/entity.types.js +0 -7
  198. package/dist/types/import-export.types.js +0 -7
  199. package/dist/types/search.types.js +0 -7
  200. package/dist/types/tag.types.js +0 -6
  201. package/dist/utils/dateUtils.js +0 -89
  202. package/dist/utils/filterUtils.js +0 -155
  203. package/dist/utils/levenshtein.js +0 -62
  204. package/dist/utils/pathUtils.js +0 -115
  205. package/dist/utils/responseFormatter.js +0 -55
  206. package/dist/utils/tagUtils.js +0 -107
  207. package/dist/utils/tfidf.js +0 -90
  208. package/dist/utils/validationHelper.js +0 -99
  209. package/dist/utils/validationUtils.js +0 -109
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Storage Factory
3
+ *
4
+ * Factory for creating IGraphStorage implementations.
5
+ * Supports different storage backends based on configuration.
6
+ *
7
+ * Supported storage types:
8
+ * - 'jsonl': JSONL file-based storage (default) - simple, human-readable
9
+ * - 'sqlite': SQLite database storage (better-sqlite3 native) - indexed, ACID transactions, FTS5
10
+ *
11
+ * @module core/StorageFactory
12
+ */
13
+ import type { IGraphStorage, StorageConfig } from '../types/index.js';
14
+ /**
15
+ * Create a storage instance based on configuration.
16
+ *
17
+ * Uses environment variable MEMORY_STORAGE_TYPE to override default.
18
+ *
19
+ * @param config - Storage configuration
20
+ * @returns IGraphStorage implementation
21
+ * @throws Error if storage type is not supported
22
+ *
23
+ * @example
24
+ * ```typescript
25
+ * // Create default JSONL storage
26
+ * const storage = createStorage({ type: 'jsonl', path: './memory.jsonl' });
27
+ *
28
+ * // Create SQLite storage
29
+ * const storage = createStorage({ type: 'sqlite', path: './memory.db' });
30
+ *
31
+ * // Or use path-only shorthand (uses MEMORY_STORAGE_TYPE env var or defaults to jsonl)
32
+ * const storage = createStorageFromPath('./memory.jsonl');
33
+ * ```
34
+ */
35
+ export declare function createStorage(config: StorageConfig): IGraphStorage;
36
+ /**
37
+ * Create a storage instance from a file path.
38
+ *
39
+ * Uses default storage type (jsonl) or MEMORY_STORAGE_TYPE env var.
40
+ *
41
+ * @param path - Path to storage file
42
+ * @returns IGraphStorage implementation
43
+ */
44
+ export declare function createStorageFromPath(path: string): IGraphStorage;
45
+ //# sourceMappingURL=StorageFactory.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"StorageFactory.d.ts","sourceRoot":"","sources":["../../src/core/StorageFactory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOtE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAiBlE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAGjE"}
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Storage Factory
3
+ *
4
+ * Factory for creating IGraphStorage implementations.
5
+ * Supports different storage backends based on configuration.
6
+ *
7
+ * Supported storage types:
8
+ * - 'jsonl': JSONL file-based storage (default) - simple, human-readable
9
+ * - 'sqlite': SQLite database storage (better-sqlite3 native) - indexed, ACID transactions, FTS5
10
+ *
11
+ * @module core/StorageFactory
12
+ */
13
+ import { GraphStorage } from './GraphStorage.js';
14
+ import { SQLiteStorage } from './SQLiteStorage.js';
15
+ /**
16
+ * Default storage type when not specified.
17
+ */
18
+ const DEFAULT_STORAGE_TYPE = 'jsonl';
19
+ /**
20
+ * Create a storage instance based on configuration.
21
+ *
22
+ * Uses environment variable MEMORY_STORAGE_TYPE to override default.
23
+ *
24
+ * @param config - Storage configuration
25
+ * @returns IGraphStorage implementation
26
+ * @throws Error if storage type is not supported
27
+ *
28
+ * @example
29
+ * ```typescript
30
+ * // Create default JSONL storage
31
+ * const storage = createStorage({ type: 'jsonl', path: './memory.jsonl' });
32
+ *
33
+ * // Create SQLite storage
34
+ * const storage = createStorage({ type: 'sqlite', path: './memory.db' });
35
+ *
36
+ * // Or use path-only shorthand (uses MEMORY_STORAGE_TYPE env var or defaults to jsonl)
37
+ * const storage = createStorageFromPath('./memory.jsonl');
38
+ * ```
39
+ */
40
+ export function createStorage(config) {
41
+ // Allow environment override
42
+ const storageType = process.env.MEMORY_STORAGE_TYPE || config.type || DEFAULT_STORAGE_TYPE;
43
+ switch (storageType) {
44
+ case 'jsonl':
45
+ return new GraphStorage(config.path);
46
+ case 'sqlite':
47
+ return new SQLiteStorage(config.path);
48
+ default:
49
+ throw new Error(`Unknown storage type: ${storageType}. ` +
50
+ `Supported types: jsonl, sqlite`);
51
+ }
52
+ }
53
+ /**
54
+ * Create a storage instance from a file path.
55
+ *
56
+ * Uses default storage type (jsonl) or MEMORY_STORAGE_TYPE env var.
57
+ *
58
+ * @param path - Path to storage file
59
+ * @returns IGraphStorage implementation
60
+ */
61
+ export function createStorageFromPath(path) {
62
+ const storageType = process.env.MEMORY_STORAGE_TYPE || DEFAULT_STORAGE_TYPE;
63
+ return createStorage({ type: storageType, path });
64
+ }
@@ -0,0 +1,464 @@
1
+ /**
2
+ * Transaction Manager
3
+ *
4
+ * Provides atomic transaction support for knowledge graph operations.
5
+ * Ensures data consistency by allowing multiple operations to be
6
+ * grouped together and committed atomically, with automatic rollback on failure.
7
+ *
8
+ * @module core/TransactionManager
9
+ */
10
+ import type { Entity, Relation, LongRunningOperationOptions, BatchOperation, BatchResult, BatchOptions } from '../types/index.js';
11
+ import type { GraphStorage } from './GraphStorage.js';
12
+ /**
13
+ * Types of operations that can be performed in a transaction.
14
+ */
15
+ export declare enum OperationType {
16
+ CREATE_ENTITY = "CREATE_ENTITY",
17
+ UPDATE_ENTITY = "UPDATE_ENTITY",
18
+ DELETE_ENTITY = "DELETE_ENTITY",
19
+ CREATE_RELATION = "CREATE_RELATION",
20
+ DELETE_RELATION = "DELETE_RELATION"
21
+ }
22
+ /**
23
+ * Represents a single operation in a transaction using discriminated union.
24
+ */
25
+ export type TransactionOperation = {
26
+ type: OperationType.CREATE_ENTITY;
27
+ data: Omit<Entity, 'createdAt' | 'lastModified'>;
28
+ } | {
29
+ type: OperationType.UPDATE_ENTITY;
30
+ data: {
31
+ name: string;
32
+ updates: Partial<Entity>;
33
+ };
34
+ } | {
35
+ type: OperationType.DELETE_ENTITY;
36
+ data: {
37
+ name: string;
38
+ };
39
+ } | {
40
+ type: OperationType.CREATE_RELATION;
41
+ data: Omit<Relation, 'createdAt' | 'lastModified'>;
42
+ } | {
43
+ type: OperationType.DELETE_RELATION;
44
+ data: {
45
+ from: string;
46
+ to: string;
47
+ relationType: string;
48
+ };
49
+ };
50
+ /**
51
+ * Transaction execution result.
52
+ */
53
+ export interface TransactionResult {
54
+ /** Whether the transaction was successful */
55
+ success: boolean;
56
+ /** Number of operations executed */
57
+ operationsExecuted: number;
58
+ /** Error message if transaction failed */
59
+ error?: string;
60
+ /** Path to rollback backup if created */
61
+ rollbackBackup?: string;
62
+ }
63
+ /**
64
+ * Manages atomic transactions for knowledge graph operations.
65
+ *
66
+ * Provides ACID-like guarantees:
67
+ * - Atomicity: All operations succeed or all fail
68
+ * - Consistency: Graph is always in a valid state
69
+ * - Isolation: Each transaction operates on a snapshot
70
+ * - Durability: Changes are persisted to disk
71
+ *
72
+ * @example
73
+ * ```typescript
74
+ * const storage = new GraphStorage('/data/memory.jsonl');
75
+ * const txManager = new TransactionManager(storage);
76
+ *
77
+ * // Begin transaction
78
+ * txManager.begin();
79
+ *
80
+ * // Stage operations
81
+ * txManager.createEntity({ name: 'Alice', entityType: 'person', observations: [] });
82
+ * txManager.createRelation({ from: 'Alice', to: 'Bob', relationType: 'knows' });
83
+ *
84
+ * // Commit atomically (or rollback on error)
85
+ * const result = await txManager.commit();
86
+ * if (result.success) {
87
+ * console.log(`Transaction completed: ${result.operationsExecuted} operations`);
88
+ * }
89
+ * ```
90
+ */
91
+ export declare class TransactionManager {
92
+ private storage;
93
+ private operations;
94
+ private inTransaction;
95
+ private ioManager;
96
+ private transactionBackup?;
97
+ constructor(storage: GraphStorage);
98
+ /**
99
+ * Begin a new transaction.
100
+ *
101
+ * Creates a backup of the current state for rollback purposes.
102
+ * Only one transaction can be active at a time.
103
+ *
104
+ * @throws {KnowledgeGraphError} If a transaction is already in progress
105
+ *
106
+ * @example
107
+ * ```typescript
108
+ * txManager.begin();
109
+ * // ... stage operations ...
110
+ * await txManager.commit();
111
+ * ```
112
+ */
113
+ begin(): void;
114
+ /**
115
+ * Stage a create entity operation.
116
+ *
117
+ * @param entity - Entity to create (without timestamps)
118
+ *
119
+ * @example
120
+ * ```typescript
121
+ * txManager.begin();
122
+ * txManager.createEntity({
123
+ * name: 'Alice',
124
+ * entityType: 'person',
125
+ * observations: ['Software engineer'],
126
+ * importance: 8
127
+ * });
128
+ * ```
129
+ */
130
+ createEntity(entity: Omit<Entity, 'createdAt' | 'lastModified'>): void;
131
+ /**
132
+ * Stage an update entity operation.
133
+ *
134
+ * @param name - Name of entity to update
135
+ * @param updates - Partial entity updates
136
+ *
137
+ * @example
138
+ * ```typescript
139
+ * txManager.begin();
140
+ * txManager.updateEntity('Alice', {
141
+ * importance: 9,
142
+ * observations: ['Lead software engineer']
143
+ * });
144
+ * ```
145
+ */
146
+ updateEntity(name: string, updates: Partial<Entity>): void;
147
+ /**
148
+ * Stage a delete entity operation.
149
+ *
150
+ * @param name - Name of entity to delete
151
+ *
152
+ * @example
153
+ * ```typescript
154
+ * txManager.begin();
155
+ * txManager.deleteEntity('OldEntity');
156
+ * ```
157
+ */
158
+ deleteEntity(name: string): void;
159
+ /**
160
+ * Stage a create relation operation.
161
+ *
162
+ * @param relation - Relation to create (without timestamps)
163
+ *
164
+ * @example
165
+ * ```typescript
166
+ * txManager.begin();
167
+ * txManager.createRelation({
168
+ * from: 'Alice',
169
+ * to: 'Bob',
170
+ * relationType: 'mentors'
171
+ * });
172
+ * ```
173
+ */
174
+ createRelation(relation: Omit<Relation, 'createdAt' | 'lastModified'>): void;
175
+ /**
176
+ * Stage a delete relation operation.
177
+ *
178
+ * @param from - Source entity name
179
+ * @param to - Target entity name
180
+ * @param relationType - Type of relation
181
+ *
182
+ * @example
183
+ * ```typescript
184
+ * txManager.begin();
185
+ * txManager.deleteRelation('Alice', 'Bob', 'mentors');
186
+ * ```
187
+ */
188
+ deleteRelation(from: string, to: string, relationType: string): void;
189
+ /**
190
+ * Commit the transaction, applying all staged operations atomically.
191
+ *
192
+ * Creates a backup before applying changes. If any operation fails,
193
+ * automatically rolls back to the pre-transaction state.
194
+ *
195
+ * Phase 9B: Supports progress tracking and cancellation via LongRunningOperationOptions.
196
+ *
197
+ * @param options - Optional progress/cancellation options (Phase 9B)
198
+ * @returns Promise resolving to transaction result
199
+ * @throws {OperationCancelledError} If operation is cancelled via signal (Phase 9B)
200
+ *
201
+ * @example
202
+ * ```typescript
203
+ * txManager.begin();
204
+ * txManager.createEntity({ name: 'Alice', entityType: 'person', observations: [] });
205
+ * txManager.createRelation({ from: 'Alice', to: 'Bob', relationType: 'knows' });
206
+ *
207
+ * const result = await txManager.commit();
208
+ * if (result.success) {
209
+ * console.log(`Committed ${result.operationsExecuted} operations`);
210
+ * } else {
211
+ * console.error(`Transaction failed: ${result.error}`);
212
+ * }
213
+ *
214
+ * // With progress tracking (Phase 9B)
215
+ * const result = await txManager.commit({
216
+ * onProgress: (p) => console.log(`${p.percentage}% complete`),
217
+ * });
218
+ * ```
219
+ */
220
+ commit(options?: LongRunningOperationOptions): Promise<TransactionResult>;
221
+ /**
222
+ * Rollback the current transaction.
223
+ *
224
+ * Restores the graph to the pre-transaction state using the backup.
225
+ * Automatically called by commit() on failure.
226
+ *
227
+ * @returns Promise resolving to rollback result
228
+ *
229
+ * @example
230
+ * ```typescript
231
+ * txManager.begin();
232
+ * txManager.createEntity({ name: 'Test', entityType: 'temp', observations: [] });
233
+ *
234
+ * // Explicit rollback (e.g., user cancellation)
235
+ * const result = await txManager.rollback();
236
+ * console.log(`Rolled back, restored from: ${result.backupUsed}`);
237
+ * ```
238
+ */
239
+ rollback(): Promise<{
240
+ success: boolean;
241
+ backupUsed?: string;
242
+ }>;
243
+ /**
244
+ * Check if a transaction is currently in progress.
245
+ *
246
+ * @returns True if transaction is active
247
+ */
248
+ isInTransaction(): boolean;
249
+ /**
250
+ * Get the number of staged operations in the current transaction.
251
+ *
252
+ * @returns Number of operations staged
253
+ */
254
+ getOperationCount(): number;
255
+ /**
256
+ * Ensure a transaction is in progress, or throw an error.
257
+ *
258
+ * @private
259
+ */
260
+ private ensureInTransaction;
261
+ /**
262
+ * Apply a single operation to the graph.
263
+ *
264
+ * @private
265
+ */
266
+ private applyOperation;
267
+ }
268
+ /**
269
+ * Phase 10 Sprint 1: Fluent API for building and executing batch transactions.
270
+ *
271
+ * BatchTransaction provides a builder pattern for accumulating multiple
272
+ * graph operations and executing them atomically in a single transaction.
273
+ * This reduces I/O overhead and ensures consistency across related changes.
274
+ *
275
+ * @example
276
+ * ```typescript
277
+ * const storage = new GraphStorage('/data/memory.jsonl');
278
+ * const batch = new BatchTransaction(storage);
279
+ *
280
+ * // Build the batch with fluent API
281
+ * const result = await batch
282
+ * .createEntity({ name: 'Alice', entityType: 'person', observations: ['Developer'] })
283
+ * .createEntity({ name: 'Bob', entityType: 'person', observations: ['Designer'] })
284
+ * .createRelation({ from: 'Alice', to: 'Bob', relationType: 'knows' })
285
+ * .updateEntity('Alice', { importance: 8 })
286
+ * .execute();
287
+ *
288
+ * if (result.success) {
289
+ * console.log(`Batch completed: ${result.operationsExecuted} operations in ${result.executionTimeMs}ms`);
290
+ * }
291
+ * ```
292
+ */
293
+ export declare class BatchTransaction {
294
+ private operations;
295
+ private storage;
296
+ /**
297
+ * Create a new BatchTransaction instance.
298
+ *
299
+ * @param storage - GraphStorage instance to execute operations against
300
+ */
301
+ constructor(storage: GraphStorage);
302
+ /**
303
+ * Add a create entity operation to the batch.
304
+ *
305
+ * @param entity - Entity to create (without timestamps)
306
+ * @returns This BatchTransaction for chaining
307
+ *
308
+ * @example
309
+ * ```typescript
310
+ * batch.createEntity({
311
+ * name: 'Alice',
312
+ * entityType: 'person',
313
+ * observations: ['Software engineer'],
314
+ * importance: 8
315
+ * });
316
+ * ```
317
+ */
318
+ createEntity(entity: Omit<Entity, 'createdAt' | 'lastModified'>): this;
319
+ /**
320
+ * Add an update entity operation to the batch.
321
+ *
322
+ * @param name - Name of entity to update
323
+ * @param updates - Partial entity updates
324
+ * @returns This BatchTransaction for chaining
325
+ *
326
+ * @example
327
+ * ```typescript
328
+ * batch.updateEntity('Alice', { importance: 9 });
329
+ * ```
330
+ */
331
+ updateEntity(name: string, updates: Partial<Entity>): this;
332
+ /**
333
+ * Add a delete entity operation to the batch.
334
+ *
335
+ * @param name - Name of entity to delete
336
+ * @returns This BatchTransaction for chaining
337
+ *
338
+ * @example
339
+ * ```typescript
340
+ * batch.deleteEntity('OldEntity');
341
+ * ```
342
+ */
343
+ deleteEntity(name: string): this;
344
+ /**
345
+ * Add a create relation operation to the batch.
346
+ *
347
+ * @param relation - Relation to create (without timestamps)
348
+ * @returns This BatchTransaction for chaining
349
+ *
350
+ * @example
351
+ * ```typescript
352
+ * batch.createRelation({
353
+ * from: 'Alice',
354
+ * to: 'Bob',
355
+ * relationType: 'mentors'
356
+ * });
357
+ * ```
358
+ */
359
+ createRelation(relation: Omit<Relation, 'createdAt' | 'lastModified'>): this;
360
+ /**
361
+ * Add a delete relation operation to the batch.
362
+ *
363
+ * @param from - Source entity name
364
+ * @param to - Target entity name
365
+ * @param relationType - Type of relation
366
+ * @returns This BatchTransaction for chaining
367
+ *
368
+ * @example
369
+ * ```typescript
370
+ * batch.deleteRelation('Alice', 'Bob', 'mentors');
371
+ * ```
372
+ */
373
+ deleteRelation(from: string, to: string, relationType: string): this;
374
+ /**
375
+ * Add observations to an existing entity.
376
+ *
377
+ * @param name - Name of entity to add observations to
378
+ * @param observations - Observations to add
379
+ * @returns This BatchTransaction for chaining
380
+ *
381
+ * @example
382
+ * ```typescript
383
+ * batch.addObservations('Alice', ['Knows TypeScript', 'Leads team']);
384
+ * ```
385
+ */
386
+ addObservations(name: string, observations: string[]): this;
387
+ /**
388
+ * Delete observations from an existing entity.
389
+ *
390
+ * @param name - Name of entity to delete observations from
391
+ * @param observations - Observations to delete
392
+ * @returns This BatchTransaction for chaining
393
+ *
394
+ * @example
395
+ * ```typescript
396
+ * batch.deleteObservations('Alice', ['Old fact']);
397
+ * ```
398
+ */
399
+ deleteObservations(name: string, observations: string[]): this;
400
+ /**
401
+ * Add multiple operations from an array.
402
+ *
403
+ * @param operations - Array of batch operations
404
+ * @returns This BatchTransaction for chaining
405
+ *
406
+ * @example
407
+ * ```typescript
408
+ * batch.addOperations([
409
+ * { type: 'createEntity', data: { name: 'A', entityType: 'x', observations: [] } },
410
+ * { type: 'createEntity', data: { name: 'B', entityType: 'x', observations: [] } }
411
+ * ]);
412
+ * ```
413
+ */
414
+ addOperations(operations: BatchOperation[]): this;
415
+ /**
416
+ * Get the number of operations in this batch.
417
+ *
418
+ * @returns Number of operations queued
419
+ */
420
+ size(): number;
421
+ /**
422
+ * Clear all operations from the batch.
423
+ *
424
+ * @returns This BatchTransaction for chaining
425
+ */
426
+ clear(): this;
427
+ /**
428
+ * Get a copy of the operations in this batch.
429
+ *
430
+ * @returns Array of batch operations
431
+ */
432
+ getOperations(): BatchOperation[];
433
+ /**
434
+ * Execute all operations in the batch atomically.
435
+ *
436
+ * All operations are applied within a single transaction. If any
437
+ * operation fails, all changes are rolled back (when stopOnError is true).
438
+ *
439
+ * @param options - Batch execution options
440
+ * @returns Promise resolving to batch result
441
+ *
442
+ * @example
443
+ * ```typescript
444
+ * const result = await batch.execute();
445
+ * if (result.success) {
446
+ * console.log(`Created ${result.entitiesCreated} entities`);
447
+ * } else {
448
+ * console.error(`Failed at operation ${result.failedOperationIndex}: ${result.error}`);
449
+ * }
450
+ * ```
451
+ */
452
+ execute(options?: BatchOptions): Promise<BatchResult>;
453
+ /**
454
+ * Validate all operations before executing.
455
+ * @private
456
+ */
457
+ private validateOperations;
458
+ /**
459
+ * Apply a single batch operation to the graph.
460
+ * @private
461
+ */
462
+ private applyBatchOperation;
463
+ }
464
+ //# sourceMappingURL=TransactionManager.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"TransactionManager.d.ts","sourceRoot":"","sources":["../../src/core/TransactionManager.ts"],"names":[],"mappings":"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"}