@claude-flow/memory 3.0.0-alpha.1

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 (214) hide show
  1. package/.agentic-flow/intelligence.json +16 -0
  2. package/README.md +249 -0
  3. package/__tests__/coverage/base.css +224 -0
  4. package/__tests__/coverage/block-navigation.js +87 -0
  5. package/__tests__/coverage/coverage-final.json +19 -0
  6. package/__tests__/coverage/favicon.png +0 -0
  7. package/__tests__/coverage/index.html +206 -0
  8. package/__tests__/coverage/lcov-report/base.css +224 -0
  9. package/__tests__/coverage/lcov-report/block-navigation.js +87 -0
  10. package/__tests__/coverage/lcov-report/favicon.png +0 -0
  11. package/__tests__/coverage/lcov-report/index.html +206 -0
  12. package/__tests__/coverage/lcov-report/prettify.css +1 -0
  13. package/__tests__/coverage/lcov-report/prettify.js +2 -0
  14. package/__tests__/coverage/lcov-report/sort-arrow-sprite.png +0 -0
  15. package/__tests__/coverage/lcov-report/sorter.js +210 -0
  16. package/__tests__/coverage/lcov-report/src/agentdb-adapter.ts.html +2737 -0
  17. package/__tests__/coverage/lcov-report/src/agentdb-backend.ts.html +3130 -0
  18. package/__tests__/coverage/lcov-report/src/application/commands/delete-memory.command.ts.html +601 -0
  19. package/__tests__/coverage/lcov-report/src/application/commands/index.html +131 -0
  20. package/__tests__/coverage/lcov-report/src/application/commands/store-memory.command.ts.html +394 -0
  21. package/__tests__/coverage/lcov-report/src/application/queries/index.html +116 -0
  22. package/__tests__/coverage/lcov-report/src/application/queries/search-memory.query.ts.html +796 -0
  23. package/__tests__/coverage/lcov-report/src/application/services/index.html +116 -0
  24. package/__tests__/coverage/lcov-report/src/application/services/memory-application-service.ts.html +793 -0
  25. package/__tests__/coverage/lcov-report/src/cache-manager.ts.html +1633 -0
  26. package/__tests__/coverage/lcov-report/src/database-provider.ts.html +1618 -0
  27. package/__tests__/coverage/lcov-report/src/domain/entities/index.html +116 -0
  28. package/__tests__/coverage/lcov-report/src/domain/entities/memory-entry.ts.html +952 -0
  29. package/__tests__/coverage/lcov-report/src/domain/services/index.html +116 -0
  30. package/__tests__/coverage/lcov-report/src/domain/services/memory-domain-service.ts.html +1294 -0
  31. package/__tests__/coverage/lcov-report/src/hnsw-index.ts.html +3124 -0
  32. package/__tests__/coverage/lcov-report/src/hybrid-backend.ts.html +2167 -0
  33. package/__tests__/coverage/lcov-report/src/index.html +266 -0
  34. package/__tests__/coverage/lcov-report/src/infrastructure/repositories/hybrid-memory-repository.ts.html +1633 -0
  35. package/__tests__/coverage/lcov-report/src/infrastructure/repositories/index.html +116 -0
  36. package/__tests__/coverage/lcov-report/src/migration.ts.html +2092 -0
  37. package/__tests__/coverage/lcov-report/src/query-builder.ts.html +1711 -0
  38. package/__tests__/coverage/lcov-report/src/sqlite-backend.ts.html +2281 -0
  39. package/__tests__/coverage/lcov-report/src/sqljs-backend.ts.html +2374 -0
  40. package/__tests__/coverage/lcov-report/src/types.ts.html +2266 -0
  41. package/__tests__/coverage/lcov.info +10238 -0
  42. package/__tests__/coverage/prettify.css +1 -0
  43. package/__tests__/coverage/prettify.js +2 -0
  44. package/__tests__/coverage/sort-arrow-sprite.png +0 -0
  45. package/__tests__/coverage/sorter.js +210 -0
  46. package/__tests__/coverage/src/agentdb-adapter.ts.html +2737 -0
  47. package/__tests__/coverage/src/agentdb-backend.ts.html +3130 -0
  48. package/__tests__/coverage/src/application/commands/delete-memory.command.ts.html +601 -0
  49. package/__tests__/coverage/src/application/commands/index.html +131 -0
  50. package/__tests__/coverage/src/application/commands/store-memory.command.ts.html +394 -0
  51. package/__tests__/coverage/src/application/queries/index.html +116 -0
  52. package/__tests__/coverage/src/application/queries/search-memory.query.ts.html +796 -0
  53. package/__tests__/coverage/src/application/services/index.html +116 -0
  54. package/__tests__/coverage/src/application/services/memory-application-service.ts.html +793 -0
  55. package/__tests__/coverage/src/cache-manager.ts.html +1633 -0
  56. package/__tests__/coverage/src/database-provider.ts.html +1618 -0
  57. package/__tests__/coverage/src/domain/entities/index.html +116 -0
  58. package/__tests__/coverage/src/domain/entities/memory-entry.ts.html +952 -0
  59. package/__tests__/coverage/src/domain/services/index.html +116 -0
  60. package/__tests__/coverage/src/domain/services/memory-domain-service.ts.html +1294 -0
  61. package/__tests__/coverage/src/hnsw-index.ts.html +3124 -0
  62. package/__tests__/coverage/src/hybrid-backend.ts.html +2167 -0
  63. package/__tests__/coverage/src/index.html +266 -0
  64. package/__tests__/coverage/src/infrastructure/repositories/hybrid-memory-repository.ts.html +1633 -0
  65. package/__tests__/coverage/src/infrastructure/repositories/index.html +116 -0
  66. package/__tests__/coverage/src/migration.ts.html +2092 -0
  67. package/__tests__/coverage/src/query-builder.ts.html +1711 -0
  68. package/__tests__/coverage/src/sqlite-backend.ts.html +2281 -0
  69. package/__tests__/coverage/src/sqljs-backend.ts.html +2374 -0
  70. package/__tests__/coverage/src/types.ts.html +2266 -0
  71. package/benchmarks/cache-hit-rate.bench.ts +535 -0
  72. package/benchmarks/hnsw-indexing.bench.ts +552 -0
  73. package/benchmarks/memory-write.bench.ts +469 -0
  74. package/benchmarks/vector-search.bench.ts +449 -0
  75. package/dist/agentdb-adapter.d.ts +146 -0
  76. package/dist/agentdb-adapter.d.ts.map +1 -0
  77. package/dist/agentdb-adapter.js +679 -0
  78. package/dist/agentdb-adapter.js.map +1 -0
  79. package/dist/agentdb-backend.d.ts +214 -0
  80. package/dist/agentdb-backend.d.ts.map +1 -0
  81. package/dist/agentdb-backend.js +827 -0
  82. package/dist/agentdb-backend.js.map +1 -0
  83. package/dist/agentdb-backend.test.d.ts +7 -0
  84. package/dist/agentdb-backend.test.d.ts.map +1 -0
  85. package/dist/agentdb-backend.test.js +258 -0
  86. package/dist/agentdb-backend.test.js.map +1 -0
  87. package/dist/application/commands/delete-memory.command.d.ts +65 -0
  88. package/dist/application/commands/delete-memory.command.d.ts.map +1 -0
  89. package/dist/application/commands/delete-memory.command.js +129 -0
  90. package/dist/application/commands/delete-memory.command.js.map +1 -0
  91. package/dist/application/commands/store-memory.command.d.ts +48 -0
  92. package/dist/application/commands/store-memory.command.d.ts.map +1 -0
  93. package/dist/application/commands/store-memory.command.js +72 -0
  94. package/dist/application/commands/store-memory.command.js.map +1 -0
  95. package/dist/application/index.d.ts +12 -0
  96. package/dist/application/index.d.ts.map +1 -0
  97. package/dist/application/index.js +15 -0
  98. package/dist/application/index.js.map +1 -0
  99. package/dist/application/queries/search-memory.query.d.ts +72 -0
  100. package/dist/application/queries/search-memory.query.d.ts.map +1 -0
  101. package/dist/application/queries/search-memory.query.js +143 -0
  102. package/dist/application/queries/search-memory.query.js.map +1 -0
  103. package/dist/application/services/memory-application-service.d.ts +121 -0
  104. package/dist/application/services/memory-application-service.d.ts.map +1 -0
  105. package/dist/application/services/memory-application-service.js +190 -0
  106. package/dist/application/services/memory-application-service.js.map +1 -0
  107. package/dist/cache-manager.d.ts +134 -0
  108. package/dist/cache-manager.d.ts.map +1 -0
  109. package/dist/cache-manager.js +407 -0
  110. package/dist/cache-manager.js.map +1 -0
  111. package/dist/database-provider.d.ts +86 -0
  112. package/dist/database-provider.d.ts.map +1 -0
  113. package/dist/database-provider.js +385 -0
  114. package/dist/database-provider.js.map +1 -0
  115. package/dist/database-provider.test.d.ts +7 -0
  116. package/dist/database-provider.test.d.ts.map +1 -0
  117. package/dist/database-provider.test.js +285 -0
  118. package/dist/database-provider.test.js.map +1 -0
  119. package/dist/domain/entities/memory-entry.d.ts +143 -0
  120. package/dist/domain/entities/memory-entry.d.ts.map +1 -0
  121. package/dist/domain/entities/memory-entry.js +226 -0
  122. package/dist/domain/entities/memory-entry.js.map +1 -0
  123. package/dist/domain/index.d.ts +11 -0
  124. package/dist/domain/index.d.ts.map +1 -0
  125. package/dist/domain/index.js +12 -0
  126. package/dist/domain/index.js.map +1 -0
  127. package/dist/domain/repositories/memory-repository.interface.d.ts +102 -0
  128. package/dist/domain/repositories/memory-repository.interface.d.ts.map +1 -0
  129. package/dist/domain/repositories/memory-repository.interface.js +11 -0
  130. package/dist/domain/repositories/memory-repository.interface.js.map +1 -0
  131. package/dist/domain/services/memory-domain-service.d.ts +105 -0
  132. package/dist/domain/services/memory-domain-service.d.ts.map +1 -0
  133. package/dist/domain/services/memory-domain-service.js +297 -0
  134. package/dist/domain/services/memory-domain-service.js.map +1 -0
  135. package/dist/hnsw-index.d.ts +111 -0
  136. package/dist/hnsw-index.d.ts.map +1 -0
  137. package/dist/hnsw-index.js +781 -0
  138. package/dist/hnsw-index.js.map +1 -0
  139. package/dist/hybrid-backend.d.ts +217 -0
  140. package/dist/hybrid-backend.d.ts.map +1 -0
  141. package/dist/hybrid-backend.js +491 -0
  142. package/dist/hybrid-backend.js.map +1 -0
  143. package/dist/hybrid-backend.test.d.ts +8 -0
  144. package/dist/hybrid-backend.test.d.ts.map +1 -0
  145. package/dist/hybrid-backend.test.js +320 -0
  146. package/dist/hybrid-backend.test.js.map +1 -0
  147. package/dist/index.d.ts +188 -0
  148. package/dist/index.d.ts.map +1 -0
  149. package/dist/index.js +345 -0
  150. package/dist/index.js.map +1 -0
  151. package/dist/infrastructure/index.d.ts +17 -0
  152. package/dist/infrastructure/index.d.ts.map +1 -0
  153. package/dist/infrastructure/index.js +16 -0
  154. package/dist/infrastructure/index.js.map +1 -0
  155. package/dist/infrastructure/repositories/hybrid-memory-repository.d.ts +66 -0
  156. package/dist/infrastructure/repositories/hybrid-memory-repository.d.ts.map +1 -0
  157. package/dist/infrastructure/repositories/hybrid-memory-repository.js +409 -0
  158. package/dist/infrastructure/repositories/hybrid-memory-repository.js.map +1 -0
  159. package/dist/migration.d.ts +68 -0
  160. package/dist/migration.d.ts.map +1 -0
  161. package/dist/migration.js +513 -0
  162. package/dist/migration.js.map +1 -0
  163. package/dist/query-builder.d.ts +211 -0
  164. package/dist/query-builder.d.ts.map +1 -0
  165. package/dist/query-builder.js +438 -0
  166. package/dist/query-builder.js.map +1 -0
  167. package/dist/sqlite-backend.d.ts +121 -0
  168. package/dist/sqlite-backend.d.ts.map +1 -0
  169. package/dist/sqlite-backend.js +564 -0
  170. package/dist/sqlite-backend.js.map +1 -0
  171. package/dist/sqljs-backend.d.ts +128 -0
  172. package/dist/sqljs-backend.d.ts.map +1 -0
  173. package/dist/sqljs-backend.js +598 -0
  174. package/dist/sqljs-backend.js.map +1 -0
  175. package/dist/types.d.ts +481 -0
  176. package/dist/types.d.ts.map +1 -0
  177. package/dist/types.js +58 -0
  178. package/dist/types.js.map +1 -0
  179. package/docs/AGENTDB-INTEGRATION.md +388 -0
  180. package/docs/CROSS_PLATFORM.md +505 -0
  181. package/docs/WINDOWS_SUPPORT.md +422 -0
  182. package/examples/agentdb-example.ts +345 -0
  183. package/examples/cross-platform-usage.ts +326 -0
  184. package/framework/benchmark.ts +112 -0
  185. package/package.json +31 -0
  186. package/src/agentdb-adapter.ts +884 -0
  187. package/src/agentdb-backend.test.ts +339 -0
  188. package/src/agentdb-backend.ts +1016 -0
  189. package/src/application/commands/delete-memory.command.ts +172 -0
  190. package/src/application/commands/store-memory.command.ts +103 -0
  191. package/src/application/index.ts +36 -0
  192. package/src/application/queries/search-memory.query.ts +237 -0
  193. package/src/application/services/memory-application-service.ts +236 -0
  194. package/src/cache-manager.ts +516 -0
  195. package/src/database-provider.test.ts +364 -0
  196. package/src/database-provider.ts +511 -0
  197. package/src/domain/entities/memory-entry.ts +289 -0
  198. package/src/domain/index.ts +35 -0
  199. package/src/domain/repositories/memory-repository.interface.ts +120 -0
  200. package/src/domain/services/memory-domain-service.ts +403 -0
  201. package/src/hnsw-index.ts +1013 -0
  202. package/src/hybrid-backend.test.ts +399 -0
  203. package/src/hybrid-backend.ts +694 -0
  204. package/src/index.ts +515 -0
  205. package/src/infrastructure/index.ts +23 -0
  206. package/src/infrastructure/repositories/hybrid-memory-repository.ts +516 -0
  207. package/src/migration.ts +669 -0
  208. package/src/query-builder.ts +542 -0
  209. package/src/sqlite-backend.ts +732 -0
  210. package/src/sqljs-backend.ts +763 -0
  211. package/src/types.ts +727 -0
  212. package/tsconfig.json +9 -0
  213. package/tsconfig.tsbuildinfo +1 -0
  214. package/verify-cross-platform.ts +170 -0
@@ -0,0 +1,134 @@
1
+ /**
2
+ * V3 Cache Manager
3
+ *
4
+ * High-performance LRU cache with TTL support, memory pressure handling,
5
+ * and write-through caching for the unified memory system.
6
+ *
7
+ * @module v3/memory/cache-manager
8
+ */
9
+ import { EventEmitter } from 'node:events';
10
+ import { CacheConfig, CacheStats, MemoryEntry } from './types.js';
11
+ /**
12
+ * High-performance LRU Cache with TTL support
13
+ *
14
+ * Features:
15
+ * - O(1) get, set, delete operations
16
+ * - LRU eviction policy
17
+ * - TTL-based expiration
18
+ * - Memory pressure handling
19
+ * - Write-through caching support
20
+ * - Performance statistics
21
+ */
22
+ export declare class CacheManager<T = MemoryEntry> extends EventEmitter {
23
+ private config;
24
+ private cache;
25
+ private head;
26
+ private tail;
27
+ private currentMemory;
28
+ private stats;
29
+ private cleanupInterval;
30
+ constructor(config?: Partial<CacheConfig>);
31
+ /**
32
+ * Get a value from the cache
33
+ */
34
+ get(key: string): T | null;
35
+ /**
36
+ * Set a value in the cache
37
+ */
38
+ set(key: string, data: T, ttl?: number): void;
39
+ /**
40
+ * Delete a value from the cache
41
+ */
42
+ delete(key: string): boolean;
43
+ /**
44
+ * Check if a key exists in the cache (without affecting LRU order)
45
+ */
46
+ has(key: string): boolean;
47
+ /**
48
+ * Clear all entries from the cache
49
+ */
50
+ clear(): void;
51
+ /**
52
+ * Get cache statistics
53
+ */
54
+ getStats(): CacheStats;
55
+ /**
56
+ * Get all keys in the cache
57
+ */
58
+ keys(): string[];
59
+ /**
60
+ * Get the size of the cache
61
+ */
62
+ get size(): number;
63
+ /**
64
+ * Prefetch multiple keys in a single batch
65
+ */
66
+ prefetch(keys: string[], loader: (keys: string[]) => Promise<Map<string, T>>, ttl?: number): Promise<void>;
67
+ /**
68
+ * Get or set pattern - get from cache or load and cache
69
+ */
70
+ getOrSet(key: string, loader: () => Promise<T>, ttl?: number): Promise<T>;
71
+ /**
72
+ * Warm the cache with initial data
73
+ */
74
+ warmUp(entries: Array<{
75
+ key: string;
76
+ data: T;
77
+ ttl?: number;
78
+ }>): void;
79
+ /**
80
+ * Invalidate entries matching a pattern
81
+ */
82
+ invalidatePattern(pattern: string | RegExp): number;
83
+ /**
84
+ * Shutdown the cache manager
85
+ */
86
+ shutdown(): void;
87
+ private mergeConfig;
88
+ private isExpired;
89
+ private estimateSize;
90
+ private addToFront;
91
+ private removeNode;
92
+ private moveToFront;
93
+ private evictLRU;
94
+ private startCleanupTimer;
95
+ private cleanupExpired;
96
+ }
97
+ /**
98
+ * Multi-layer cache with L1 (memory) and L2 (storage) tiers
99
+ */
100
+ export declare class TieredCacheManager<T = MemoryEntry> extends EventEmitter {
101
+ private l1Cache;
102
+ private l2Loader;
103
+ private l2Writer;
104
+ constructor(l1Config?: Partial<CacheConfig>, l2Options?: {
105
+ loader: (key: string) => Promise<T | null>;
106
+ writer?: (key: string, value: T) => Promise<void>;
107
+ });
108
+ /**
109
+ * Get from tiered cache
110
+ */
111
+ get(key: string): Promise<T | null>;
112
+ /**
113
+ * Set in tiered cache
114
+ */
115
+ set(key: string, value: T, ttl?: number): Promise<void>;
116
+ /**
117
+ * Delete from tiered cache
118
+ */
119
+ delete(key: string): boolean;
120
+ /**
121
+ * Get L1 cache statistics
122
+ */
123
+ getStats(): CacheStats;
124
+ /**
125
+ * Clear L1 cache
126
+ */
127
+ clear(): void;
128
+ /**
129
+ * Shutdown tiered cache
130
+ */
131
+ shutdown(): void;
132
+ }
133
+ export default CacheManager;
134
+ //# sourceMappingURL=cache-manager.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../src/cache-manager.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,407 @@
1
+ /**
2
+ * V3 Cache Manager
3
+ *
4
+ * High-performance LRU cache with TTL support, memory pressure handling,
5
+ * and write-through caching for the unified memory system.
6
+ *
7
+ * @module v3/memory/cache-manager
8
+ */
9
+ import { EventEmitter } from 'node:events';
10
+ /**
11
+ * High-performance LRU Cache with TTL support
12
+ *
13
+ * Features:
14
+ * - O(1) get, set, delete operations
15
+ * - LRU eviction policy
16
+ * - TTL-based expiration
17
+ * - Memory pressure handling
18
+ * - Write-through caching support
19
+ * - Performance statistics
20
+ */
21
+ export class CacheManager extends EventEmitter {
22
+ config;
23
+ cache = new Map();
24
+ head = null;
25
+ tail = null;
26
+ currentMemory = 0;
27
+ // Statistics
28
+ stats = {
29
+ hits: 0,
30
+ misses: 0,
31
+ evictions: 0,
32
+ expirations: 0,
33
+ writes: 0,
34
+ };
35
+ // Cleanup timer
36
+ cleanupInterval = null;
37
+ constructor(config = {}) {
38
+ super();
39
+ this.config = this.mergeConfig(config);
40
+ this.startCleanupTimer();
41
+ }
42
+ /**
43
+ * Get a value from the cache
44
+ */
45
+ get(key) {
46
+ const node = this.cache.get(key);
47
+ if (!node) {
48
+ this.stats.misses++;
49
+ this.emit('cache:miss', { key });
50
+ return null;
51
+ }
52
+ // Check if expired
53
+ if (this.isExpired(node.value)) {
54
+ this.delete(key);
55
+ this.stats.misses++;
56
+ this.stats.expirations++;
57
+ this.emit('cache:expired', { key });
58
+ return null;
59
+ }
60
+ // Update access time and count
61
+ node.value.lastAccessedAt = Date.now();
62
+ node.value.accessCount++;
63
+ // Move to front (most recently used)
64
+ this.moveToFront(node);
65
+ this.stats.hits++;
66
+ this.emit('cache:hit', { key });
67
+ return node.value.data;
68
+ }
69
+ /**
70
+ * Set a value in the cache
71
+ */
72
+ set(key, data, ttl) {
73
+ const now = Date.now();
74
+ const entryTtl = ttl || this.config.ttl;
75
+ // Check if key already exists
76
+ const existingNode = this.cache.get(key);
77
+ if (existingNode) {
78
+ // Update existing entry
79
+ existingNode.value.data = data;
80
+ existingNode.value.cachedAt = now;
81
+ existingNode.value.expiresAt = now + entryTtl;
82
+ existingNode.value.lastAccessedAt = now;
83
+ this.moveToFront(existingNode);
84
+ this.stats.writes++;
85
+ return;
86
+ }
87
+ // Calculate memory for new entry
88
+ const entryMemory = this.estimateSize(data);
89
+ // Evict entries if needed for memory pressure
90
+ if (this.config.maxMemory) {
91
+ while (this.currentMemory + entryMemory > this.config.maxMemory &&
92
+ this.cache.size > 0) {
93
+ this.evictLRU();
94
+ }
95
+ }
96
+ // Evict entries if at capacity
97
+ while (this.cache.size >= this.config.maxSize) {
98
+ this.evictLRU();
99
+ }
100
+ // Create new node
101
+ const cachedEntry = {
102
+ data,
103
+ cachedAt: now,
104
+ expiresAt: now + entryTtl,
105
+ lastAccessedAt: now,
106
+ accessCount: 0,
107
+ };
108
+ const node = {
109
+ key,
110
+ value: cachedEntry,
111
+ prev: null,
112
+ next: null,
113
+ };
114
+ // Add to cache
115
+ this.cache.set(key, node);
116
+ this.addToFront(node);
117
+ this.currentMemory += entryMemory;
118
+ this.stats.writes++;
119
+ this.emit('cache:set', { key, ttl: entryTtl });
120
+ }
121
+ /**
122
+ * Delete a value from the cache
123
+ */
124
+ delete(key) {
125
+ const node = this.cache.get(key);
126
+ if (!node) {
127
+ return false;
128
+ }
129
+ this.removeNode(node);
130
+ this.cache.delete(key);
131
+ this.currentMemory -= this.estimateSize(node.value.data);
132
+ this.emit('cache:delete', { key });
133
+ return true;
134
+ }
135
+ /**
136
+ * Check if a key exists in the cache (without affecting LRU order)
137
+ */
138
+ has(key) {
139
+ const node = this.cache.get(key);
140
+ if (!node)
141
+ return false;
142
+ if (this.isExpired(node.value)) {
143
+ this.delete(key);
144
+ return false;
145
+ }
146
+ return true;
147
+ }
148
+ /**
149
+ * Clear all entries from the cache
150
+ */
151
+ clear() {
152
+ this.cache.clear();
153
+ this.head = null;
154
+ this.tail = null;
155
+ this.currentMemory = 0;
156
+ this.emit('cache:cleared', { previousSize: this.cache.size });
157
+ }
158
+ /**
159
+ * Get cache statistics
160
+ */
161
+ getStats() {
162
+ const total = this.stats.hits + this.stats.misses;
163
+ return {
164
+ size: this.cache.size,
165
+ hitRate: total > 0 ? this.stats.hits / total : 0,
166
+ hits: this.stats.hits,
167
+ misses: this.stats.misses,
168
+ evictions: this.stats.evictions,
169
+ memoryUsage: this.currentMemory,
170
+ };
171
+ }
172
+ /**
173
+ * Get all keys in the cache
174
+ */
175
+ keys() {
176
+ return Array.from(this.cache.keys());
177
+ }
178
+ /**
179
+ * Get the size of the cache
180
+ */
181
+ get size() {
182
+ return this.cache.size;
183
+ }
184
+ /**
185
+ * Prefetch multiple keys in a single batch
186
+ */
187
+ async prefetch(keys, loader, ttl) {
188
+ const missing = keys.filter((key) => !this.has(key));
189
+ if (missing.length === 0) {
190
+ return;
191
+ }
192
+ const data = await loader(missing);
193
+ for (const [key, value] of data) {
194
+ this.set(key, value, ttl);
195
+ }
196
+ this.emit('cache:prefetched', { keys: missing.length });
197
+ }
198
+ /**
199
+ * Get or set pattern - get from cache or load and cache
200
+ */
201
+ async getOrSet(key, loader, ttl) {
202
+ const cached = this.get(key);
203
+ if (cached !== null) {
204
+ return cached;
205
+ }
206
+ const data = await loader();
207
+ this.set(key, data, ttl);
208
+ return data;
209
+ }
210
+ /**
211
+ * Warm the cache with initial data
212
+ */
213
+ warmUp(entries) {
214
+ for (const entry of entries) {
215
+ this.set(entry.key, entry.data, entry.ttl);
216
+ }
217
+ this.emit('cache:warmedUp', { count: entries.length });
218
+ }
219
+ /**
220
+ * Invalidate entries matching a pattern
221
+ */
222
+ invalidatePattern(pattern) {
223
+ const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
224
+ let invalidated = 0;
225
+ for (const key of this.cache.keys()) {
226
+ if (regex.test(key)) {
227
+ this.delete(key);
228
+ invalidated++;
229
+ }
230
+ }
231
+ this.emit('cache:invalidated', { pattern: pattern.toString(), count: invalidated });
232
+ return invalidated;
233
+ }
234
+ /**
235
+ * Shutdown the cache manager
236
+ */
237
+ shutdown() {
238
+ if (this.cleanupInterval) {
239
+ clearInterval(this.cleanupInterval);
240
+ this.cleanupInterval = null;
241
+ }
242
+ this.clear();
243
+ this.emit('cache:shutdown');
244
+ }
245
+ // ===== Private Methods =====
246
+ mergeConfig(config) {
247
+ return {
248
+ maxSize: config.maxSize || 10000,
249
+ ttl: config.ttl || 300000, // 5 minutes default
250
+ lruEnabled: config.lruEnabled !== false,
251
+ maxMemory: config.maxMemory,
252
+ writeThrough: config.writeThrough || false,
253
+ };
254
+ }
255
+ isExpired(entry) {
256
+ return Date.now() > entry.expiresAt;
257
+ }
258
+ estimateSize(data) {
259
+ try {
260
+ return JSON.stringify(data).length * 2; // Rough UTF-16 estimate
261
+ }
262
+ catch {
263
+ return 1000; // Default for non-serializable objects
264
+ }
265
+ }
266
+ addToFront(node) {
267
+ node.prev = null;
268
+ node.next = this.head;
269
+ if (this.head) {
270
+ this.head.prev = node;
271
+ }
272
+ this.head = node;
273
+ if (!this.tail) {
274
+ this.tail = node;
275
+ }
276
+ }
277
+ removeNode(node) {
278
+ if (node.prev) {
279
+ node.prev.next = node.next;
280
+ }
281
+ else {
282
+ this.head = node.next;
283
+ }
284
+ if (node.next) {
285
+ node.next.prev = node.prev;
286
+ }
287
+ else {
288
+ this.tail = node.prev;
289
+ }
290
+ }
291
+ moveToFront(node) {
292
+ if (node === this.head)
293
+ return;
294
+ this.removeNode(node);
295
+ this.addToFront(node);
296
+ }
297
+ evictLRU() {
298
+ if (!this.tail)
299
+ return;
300
+ const evictedKey = this.tail.key;
301
+ const evictedSize = this.estimateSize(this.tail.value.data);
302
+ this.removeNode(this.tail);
303
+ this.cache.delete(evictedKey);
304
+ this.currentMemory -= evictedSize;
305
+ this.stats.evictions++;
306
+ this.emit('cache:eviction', { key: evictedKey });
307
+ }
308
+ startCleanupTimer() {
309
+ // Clean up expired entries every minute
310
+ this.cleanupInterval = setInterval(() => {
311
+ this.cleanupExpired();
312
+ }, 60000);
313
+ }
314
+ cleanupExpired() {
315
+ const now = Date.now();
316
+ let cleaned = 0;
317
+ for (const [key, node] of this.cache) {
318
+ if (node.value.expiresAt < now) {
319
+ this.delete(key);
320
+ cleaned++;
321
+ }
322
+ }
323
+ if (cleaned > 0) {
324
+ this.emit('cache:cleanup', { expired: cleaned });
325
+ }
326
+ }
327
+ }
328
+ /**
329
+ * Multi-layer cache with L1 (memory) and L2 (storage) tiers
330
+ */
331
+ export class TieredCacheManager extends EventEmitter {
332
+ l1Cache;
333
+ l2Loader = null;
334
+ l2Writer = null;
335
+ constructor(l1Config = {}, l2Options) {
336
+ super();
337
+ this.l1Cache = new CacheManager(l1Config);
338
+ if (l2Options) {
339
+ this.l2Loader = l2Options.loader;
340
+ this.l2Writer = l2Options.writer ?? null;
341
+ }
342
+ // Forward L1 events
343
+ this.l1Cache.on('cache:hit', (data) => this.emit('l1:hit', data));
344
+ this.l1Cache.on('cache:miss', (data) => this.emit('l1:miss', data));
345
+ this.l1Cache.on('cache:eviction', (data) => this.emit('l1:eviction', data));
346
+ }
347
+ /**
348
+ * Get from tiered cache
349
+ */
350
+ async get(key) {
351
+ // Try L1 first
352
+ const l1Result = this.l1Cache.get(key);
353
+ if (l1Result !== null) {
354
+ return l1Result;
355
+ }
356
+ // Try L2 if available
357
+ if (this.l2Loader) {
358
+ const l2Result = await this.l2Loader(key);
359
+ if (l2Result !== null) {
360
+ // Promote to L1
361
+ this.l1Cache.set(key, l2Result);
362
+ this.emit('l2:hit', { key });
363
+ return l2Result;
364
+ }
365
+ this.emit('l2:miss', { key });
366
+ }
367
+ return null;
368
+ }
369
+ /**
370
+ * Set in tiered cache
371
+ */
372
+ async set(key, value, ttl) {
373
+ // Write to L1
374
+ this.l1Cache.set(key, value, ttl);
375
+ // Write-through to L2 if configured
376
+ if (this.l2Writer) {
377
+ await this.l2Writer(key, value);
378
+ this.emit('l2:write', { key });
379
+ }
380
+ }
381
+ /**
382
+ * Delete from tiered cache
383
+ */
384
+ delete(key) {
385
+ return this.l1Cache.delete(key);
386
+ }
387
+ /**
388
+ * Get L1 cache statistics
389
+ */
390
+ getStats() {
391
+ return this.l1Cache.getStats();
392
+ }
393
+ /**
394
+ * Clear L1 cache
395
+ */
396
+ clear() {
397
+ this.l1Cache.clear();
398
+ }
399
+ /**
400
+ * Shutdown tiered cache
401
+ */
402
+ shutdown() {
403
+ this.l1Cache.shutdown();
404
+ }
405
+ }
406
+ export default CacheManager;
407
+ //# sourceMappingURL=cache-manager.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cache-manager.js","sourceRoot":"","sources":["../src/cache-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAmB3C;;;;;;;;;;GAUG;AACH,MAAM,OAAO,YAA8B,SAAQ,YAAY;IACrD,MAAM,CAAc;IACpB,KAAK,GAA4B,IAAI,GAAG,EAAE,CAAC;IAC3C,IAAI,GAAsB,IAAI,CAAC;IAC/B,IAAI,GAAsB,IAAI,CAAC;IAC/B,aAAa,GAAW,CAAC,CAAC;IAElC,aAAa;IACL,KAAK,GAMT;QACF,IAAI,EAAE,CAAC;QACP,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,CAAC;QACZ,WAAW,EAAE,CAAC;QACd,MAAM,EAAE,CAAC;KACV,CAAC;IAEF,gBAAgB;IACR,eAAe,GAA0B,IAAI,CAAC;IAEtD,YAAY,SAA+B,EAAE;QAC3C,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,GAAW;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEjC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YACjC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,mBAAmB;QACnB,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjB,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACpB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YACpC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,+BAA+B;QAC/B,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QAEzB,qCAAqC;QACrC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAEvB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAEhC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,GAAW,EAAE,IAAO,EAAE,GAAY;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;QAExC,8BAA8B;QAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,YAAY,EAAE,CAAC;YACjB,wBAAwB;YACxB,YAAY,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;YAC/B,YAAY,CAAC,KAAK,CAAC,QAAQ,GAAG,GAAG,CAAC;YAClC,YAAY,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,GAAG,QAAQ,CAAC;YAC9C,YAAY,CAAC,KAAK,CAAC,cAAc,GAAG,GAAG,CAAC;YAExC,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;YAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QAED,iCAAiC;QACjC,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QAE5C,8CAA8C;QAC9C,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC1B,OACE,IAAI,CAAC,aAAa,GAAG,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS;gBACxD,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EACnB,CAAC;gBACD,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,CAAC;QACH,CAAC;QAED,+BAA+B;QAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAC9C,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,CAAC;QAED,kBAAkB;QAClB,MAAM,WAAW,GAAmB;YAClC,IAAI;YACJ,QAAQ,EAAE,GAAG;YACb,SAAS,EAAE,GAAG,GAAG,QAAQ;YACzB,cAAc,EAAE,GAAG;YACnB,WAAW,EAAE,CAAC;SACf,CAAC;QAEF,MAAM,IAAI,GAAe;YACvB,GAAG;YACH,KAAK,EAAE,WAAW;YAClB,IAAI,EAAE,IAAI;YACV,IAAI,EAAE,IAAI;SACX,CAAC;QAEF,eAAe;QACf,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,aAAa,IAAI,WAAW,CAAC;QAClC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAEpB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IACjD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,GAAW;QAChB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAEzD,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,GAAW;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;QAEvB,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAChE,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QAClD,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACrB,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YAChD,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACrB,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;YACzB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS;YAC/B,WAAW,EAAE,IAAI,CAAC,aAAa;SAChC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ,CACZ,IAAc,EACd,MAAmD,EACnD,GAAY;QAEZ,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAErD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QAEnC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;YAChC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAC5B,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ,CACZ,GAAW,EACX,MAAwB,EACxB,GAAY;QAEZ,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,MAAM,EAAE,CAAC;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,OAAsD;QAC3D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,iBAAiB,CAAC,OAAwB;QACxC,MAAM,KAAK,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAC1E,IAAI,WAAW,GAAG,CAAC,CAAC;QAEpB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjB,WAAW,EAAE,CAAC;YAChB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;QACpF,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YACpC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAC9B,CAAC;IAED,8BAA8B;IAEtB,WAAW,CAAC,MAA4B;QAC9C,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAK;YAChC,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,MAAM,EAAE,oBAAoB;YAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,KAAK,KAAK;YACvC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,KAAK;SAC3C,CAAC;IACJ,CAAC;IAEO,SAAS,CAAC,KAAqB;QACrC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC;IACtC,CAAC;IAEO,YAAY,CAAC,IAAO;QAC1B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,wBAAwB;QAClE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,CAAC,uCAAuC;QACtD,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,IAAgB;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAEtB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACxB,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAEjB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,IAAgB;QACjC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACxB,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACxB,CAAC;IACH,CAAC;IAEO,WAAW,CAAC,IAAgB;QAClC,IAAI,IAAI,KAAK,IAAI,CAAC,IAAI;YAAE,OAAO;QAE/B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAEO,QAAQ;QACd,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,OAAO;QAEvB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACjC,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAE5D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC9B,IAAI,CAAC,aAAa,IAAI,WAAW,CAAC;QAClC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QAEvB,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC;IACnD,CAAC;IAEO,iBAAiB;QACvB,wCAAwC;QACxC,IAAI,CAAC,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE;YACtC,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,CAAC,EAAE,KAAK,CAAC,CAAC;IACZ,CAAC;IAEO,cAAc;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,OAAO,GAAG,CAAC,CAAC;QAEhB,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACrC,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;gBAC/B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjB,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QAED,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAoC,SAAQ,YAAY;IAC3D,OAAO,CAAkB;IACzB,QAAQ,GAAgD,IAAI,CAAC;IAC7D,QAAQ,GAAsD,IAAI,CAAC;IAE3E,YACE,WAAiC,EAAE,EACnC,SAGC;QAED,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,OAAO,GAAG,IAAI,YAAY,CAAI,QAAQ,CAAC,CAAC;QAE7C,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC;YACjC,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC;QAC3C,CAAC;QAED,oBAAoB;QACpB,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;QAClE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;QACpE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,gBAAgB,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,eAAe;QACf,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,sBAAsB;QACtB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC1C,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACtB,gBAAgB;gBAChB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;gBAChC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC7B,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAQ,EAAE,GAAY;QAC3C,cAAc;QACd,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAElC,oCAAoC;QACpC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;CACF;AAED,eAAe,YAAY,CAAC"}
@@ -0,0 +1,86 @@
1
+ /**
2
+ * DatabaseProvider - Platform-aware database selection
3
+ *
4
+ * Automatically selects best backend:
5
+ * - Linux/macOS: better-sqlite3 (native, fast)
6
+ * - Windows: sql.js (WASM, universal) when native fails
7
+ * - Fallback: JSON file storage
8
+ *
9
+ * @module v3/memory/database-provider
10
+ */
11
+ import { IMemoryBackend } from './types.js';
12
+ /**
13
+ * Available database provider types
14
+ */
15
+ export type DatabaseProvider = 'better-sqlite3' | 'sql.js' | 'json' | 'auto';
16
+ /**
17
+ * Database creation options
18
+ */
19
+ export interface DatabaseOptions {
20
+ /** Preferred provider (auto = platform-aware selection) */
21
+ provider?: DatabaseProvider;
22
+ /** Enable verbose logging */
23
+ verbose?: boolean;
24
+ /** Enable WAL mode (better-sqlite3 only) */
25
+ walMode?: boolean;
26
+ /** Enable query optimization */
27
+ optimize?: boolean;
28
+ /** Default namespace */
29
+ defaultNamespace?: string;
30
+ /** Maximum entries before auto-cleanup */
31
+ maxEntries?: number;
32
+ /** Auto-persist interval for sql.js (milliseconds) */
33
+ autoPersistInterval?: number;
34
+ /** Path to sql.js WASM file */
35
+ wasmPath?: string;
36
+ }
37
+ /**
38
+ * Platform detection result
39
+ */
40
+ interface PlatformInfo {
41
+ os: string;
42
+ isWindows: boolean;
43
+ isMacOS: boolean;
44
+ isLinux: boolean;
45
+ recommendedProvider: DatabaseProvider;
46
+ }
47
+ /**
48
+ * Create a database instance with platform-aware provider selection
49
+ *
50
+ * @param path - Database file path (:memory: for in-memory)
51
+ * @param options - Database configuration options
52
+ * @returns Initialized database backend
53
+ *
54
+ * @example
55
+ * ```typescript
56
+ * // Auto-select best provider for platform
57
+ * const db = await createDatabase('./data/memory.db');
58
+ *
59
+ * // Force specific provider
60
+ * const db = await createDatabase('./data/memory.db', {
61
+ * provider: 'sql.js'
62
+ * });
63
+ *
64
+ * // With custom options
65
+ * const db = await createDatabase('./data/memory.db', {
66
+ * verbose: true,
67
+ * optimize: true,
68
+ * autoPersistInterval: 10000
69
+ * });
70
+ * ```
71
+ */
72
+ export declare function createDatabase(path: string, options?: DatabaseOptions): Promise<IMemoryBackend>;
73
+ /**
74
+ * Get platform information
75
+ */
76
+ export declare function getPlatformInfo(): PlatformInfo;
77
+ /**
78
+ * Check which providers are available
79
+ */
80
+ export declare function getAvailableProviders(): Promise<{
81
+ betterSqlite3: boolean;
82
+ sqlJs: boolean;
83
+ json: boolean;
84
+ }>;
85
+ export {};
86
+ //# sourceMappingURL=database-provider.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"database-provider.d.ts","sourceRoot":"","sources":["../src/database-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EACL,cAAc,EASf,MAAM,YAAY,CAAC;AAIpB;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAE5B,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,wBAAwB;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,sDAAsD;IACtD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,UAAU,YAAY;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,mBAAmB,EAAE,gBAAgB,CAAC;CACvC;AAmGD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAsEzB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC;IACrD,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf,CAAC,CAMD"}