@cyanheads/mcp-ts-core 0.1.0-beta.12

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 (485) hide show
  1. package/CLAUDE.md +583 -0
  2. package/LICENSE +201 -0
  3. package/README.md +287 -0
  4. package/biome.json +103 -0
  5. package/dist/app.d.ts +82 -0
  6. package/dist/app.d.ts.map +1 -0
  7. package/dist/app.js +222 -0
  8. package/dist/app.js.map +1 -0
  9. package/dist/cli/init.d.ts +8 -0
  10. package/dist/cli/init.d.ts.map +1 -0
  11. package/dist/cli/init.js +161 -0
  12. package/dist/cli/init.js.map +1 -0
  13. package/dist/config/index.d.ts +349 -0
  14. package/dist/config/index.d.ts.map +1 -0
  15. package/dist/config/index.js +464 -0
  16. package/dist/config/index.js.map +1 -0
  17. package/dist/context.d.ts +119 -0
  18. package/dist/context.d.ts.map +1 -0
  19. package/dist/context.js +144 -0
  20. package/dist/context.js.map +1 -0
  21. package/dist/index.d.ts +8 -0
  22. package/dist/index.d.ts.map +1 -0
  23. package/dist/index.js +9 -0
  24. package/dist/index.js.map +1 -0
  25. package/dist/mcp-server/prompts/prompt-registration.d.ts +33 -0
  26. package/dist/mcp-server/prompts/prompt-registration.d.ts.map +1 -0
  27. package/dist/mcp-server/prompts/prompt-registration.js +91 -0
  28. package/dist/mcp-server/prompts/prompt-registration.js.map +1 -0
  29. package/dist/mcp-server/prompts/utils/newPromptDefinition.d.ts +49 -0
  30. package/dist/mcp-server/prompts/utils/newPromptDefinition.d.ts.map +1 -0
  31. package/dist/mcp-server/prompts/utils/newPromptDefinition.js +39 -0
  32. package/dist/mcp-server/prompts/utils/newPromptDefinition.js.map +1 -0
  33. package/dist/mcp-server/prompts/utils/promptDefinition.d.ts +37 -0
  34. package/dist/mcp-server/prompts/utils/promptDefinition.d.ts.map +1 -0
  35. package/dist/mcp-server/prompts/utils/promptDefinition.js +2 -0
  36. package/dist/mcp-server/prompts/utils/promptDefinition.js.map +1 -0
  37. package/dist/mcp-server/resources/resource-registration.d.ts +27 -0
  38. package/dist/mcp-server/resources/resource-registration.d.ts.map +1 -0
  39. package/dist/mcp-server/resources/resource-registration.js +85 -0
  40. package/dist/mcp-server/resources/resource-registration.js.map +1 -0
  41. package/dist/mcp-server/resources/utils/newResourceDefinition.d.ts +84 -0
  42. package/dist/mcp-server/resources/utils/newResourceDefinition.d.ts.map +1 -0
  43. package/dist/mcp-server/resources/utils/newResourceDefinition.js +40 -0
  44. package/dist/mcp-server/resources/utils/newResourceDefinition.js.map +1 -0
  45. package/dist/mcp-server/resources/utils/newResourceHandlerFactory.d.ts +32 -0
  46. package/dist/mcp-server/resources/utils/newResourceHandlerFactory.d.ts.map +1 -0
  47. package/dist/mcp-server/resources/utils/newResourceHandlerFactory.js +103 -0
  48. package/dist/mcp-server/resources/utils/newResourceHandlerFactory.js.map +1 -0
  49. package/dist/mcp-server/resources/utils/resourceDefinition.d.ts +94 -0
  50. package/dist/mcp-server/resources/utils/resourceDefinition.d.ts.map +1 -0
  51. package/dist/mcp-server/resources/utils/resourceDefinition.js +2 -0
  52. package/dist/mcp-server/resources/utils/resourceDefinition.js.map +1 -0
  53. package/dist/mcp-server/resources/utils/resourceHandlerFactory.d.ts +14 -0
  54. package/dist/mcp-server/resources/utils/resourceHandlerFactory.d.ts.map +1 -0
  55. package/dist/mcp-server/resources/utils/resourceHandlerFactory.js +111 -0
  56. package/dist/mcp-server/resources/utils/resourceHandlerFactory.js.map +1 -0
  57. package/dist/mcp-server/roots/roots-registration.d.ts +22 -0
  58. package/dist/mcp-server/roots/roots-registration.d.ts.map +1 -0
  59. package/dist/mcp-server/roots/roots-registration.js +25 -0
  60. package/dist/mcp-server/roots/roots-registration.js.map +1 -0
  61. package/dist/mcp-server/server.d.ts +34 -0
  62. package/dist/mcp-server/server.d.ts.map +1 -0
  63. package/dist/mcp-server/server.js +62 -0
  64. package/dist/mcp-server/server.js.map +1 -0
  65. package/dist/mcp-server/tasks/core/sessionAwareTaskStore.d.ts +42 -0
  66. package/dist/mcp-server/tasks/core/sessionAwareTaskStore.d.ts.map +1 -0
  67. package/dist/mcp-server/tasks/core/sessionAwareTaskStore.js +70 -0
  68. package/dist/mcp-server/tasks/core/sessionAwareTaskStore.js.map +1 -0
  69. package/dist/mcp-server/tasks/core/storageBackedTaskStore.d.ts +109 -0
  70. package/dist/mcp-server/tasks/core/storageBackedTaskStore.d.ts.map +1 -0
  71. package/dist/mcp-server/tasks/core/storageBackedTaskStore.js +209 -0
  72. package/dist/mcp-server/tasks/core/storageBackedTaskStore.js.map +1 -0
  73. package/dist/mcp-server/tasks/core/taskManager.d.ts +103 -0
  74. package/dist/mcp-server/tasks/core/taskManager.d.ts.map +1 -0
  75. package/dist/mcp-server/tasks/core/taskManager.js +144 -0
  76. package/dist/mcp-server/tasks/core/taskManager.js.map +1 -0
  77. package/dist/mcp-server/tasks/core/taskTypes.d.ts +11 -0
  78. package/dist/mcp-server/tasks/core/taskTypes.d.ts.map +1 -0
  79. package/dist/mcp-server/tasks/core/taskTypes.js +13 -0
  80. package/dist/mcp-server/tasks/core/taskTypes.js.map +1 -0
  81. package/dist/mcp-server/tasks/utils/taskToolDefinition.d.ts +108 -0
  82. package/dist/mcp-server/tasks/utils/taskToolDefinition.d.ts.map +1 -0
  83. package/dist/mcp-server/tasks/utils/taskToolDefinition.js +14 -0
  84. package/dist/mcp-server/tasks/utils/taskToolDefinition.js.map +1 -0
  85. package/dist/mcp-server/tools/tool-registration.d.ts +49 -0
  86. package/dist/mcp-server/tools/tool-registration.d.ts.map +1 -0
  87. package/dist/mcp-server/tools/tool-registration.js +269 -0
  88. package/dist/mcp-server/tools/tool-registration.js.map +1 -0
  89. package/dist/mcp-server/tools/utils/newToolDefinition.d.ts +73 -0
  90. package/dist/mcp-server/tools/utils/newToolDefinition.d.ts.map +1 -0
  91. package/dist/mcp-server/tools/utils/newToolDefinition.js +45 -0
  92. package/dist/mcp-server/tools/utils/newToolDefinition.js.map +1 -0
  93. package/dist/mcp-server/tools/utils/newToolHandlerFactory.d.ts +33 -0
  94. package/dist/mcp-server/tools/utils/newToolHandlerFactory.d.ts.map +1 -0
  95. package/dist/mcp-server/tools/utils/newToolHandlerFactory.js +107 -0
  96. package/dist/mcp-server/tools/utils/newToolHandlerFactory.js.map +1 -0
  97. package/dist/mcp-server/tools/utils/toolDefinition.d.ts +118 -0
  98. package/dist/mcp-server/tools/utils/toolDefinition.d.ts.map +1 -0
  99. package/dist/mcp-server/tools/utils/toolDefinition.js +2 -0
  100. package/dist/mcp-server/tools/utils/toolDefinition.js.map +1 -0
  101. package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts +34 -0
  102. package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts.map +1 -0
  103. package/dist/mcp-server/tools/utils/toolHandlerFactory.js +68 -0
  104. package/dist/mcp-server/tools/utils/toolHandlerFactory.js.map +1 -0
  105. package/dist/mcp-server/transports/ITransport.d.ts +15 -0
  106. package/dist/mcp-server/transports/ITransport.d.ts.map +1 -0
  107. package/dist/mcp-server/transports/ITransport.js +2 -0
  108. package/dist/mcp-server/transports/ITransport.js.map +1 -0
  109. package/dist/mcp-server/transports/auth/authFactory.d.ts +11 -0
  110. package/dist/mcp-server/transports/auth/authFactory.d.ts.map +1 -0
  111. package/dist/mcp-server/transports/auth/authFactory.js +43 -0
  112. package/dist/mcp-server/transports/auth/authFactory.js.map +1 -0
  113. package/dist/mcp-server/transports/auth/authMiddleware.d.ts +24 -0
  114. package/dist/mcp-server/transports/auth/authMiddleware.d.ts.map +1 -0
  115. package/dist/mcp-server/transports/auth/authMiddleware.js +69 -0
  116. package/dist/mcp-server/transports/auth/authMiddleware.js.map +1 -0
  117. package/dist/mcp-server/transports/auth/lib/authContext.d.ts +34 -0
  118. package/dist/mcp-server/transports/auth/lib/authContext.d.ts.map +1 -0
  119. package/dist/mcp-server/transports/auth/lib/authContext.js +25 -0
  120. package/dist/mcp-server/transports/auth/lib/authContext.js.map +1 -0
  121. package/dist/mcp-server/transports/auth/lib/authTypes.d.ts +19 -0
  122. package/dist/mcp-server/transports/auth/lib/authTypes.d.ts.map +1 -0
  123. package/dist/mcp-server/transports/auth/lib/authTypes.js +2 -0
  124. package/dist/mcp-server/transports/auth/lib/authTypes.js.map +1 -0
  125. package/dist/mcp-server/transports/auth/lib/authUtils.d.ts +18 -0
  126. package/dist/mcp-server/transports/auth/lib/authUtils.d.ts.map +1 -0
  127. package/dist/mcp-server/transports/auth/lib/authUtils.js +64 -0
  128. package/dist/mcp-server/transports/auth/lib/authUtils.js.map +1 -0
  129. package/dist/mcp-server/transports/auth/lib/checkScopes.d.ts +25 -0
  130. package/dist/mcp-server/transports/auth/lib/checkScopes.d.ts.map +1 -0
  131. package/dist/mcp-server/transports/auth/lib/checkScopes.js +34 -0
  132. package/dist/mcp-server/transports/auth/lib/checkScopes.js.map +1 -0
  133. package/dist/mcp-server/transports/auth/lib/claimParser.d.ts +34 -0
  134. package/dist/mcp-server/transports/auth/lib/claimParser.d.ts.map +1 -0
  135. package/dist/mcp-server/transports/auth/lib/claimParser.js +58 -0
  136. package/dist/mcp-server/transports/auth/lib/claimParser.js.map +1 -0
  137. package/dist/mcp-server/transports/auth/lib/withAuth.d.ts +25 -0
  138. package/dist/mcp-server/transports/auth/lib/withAuth.d.ts.map +1 -0
  139. package/dist/mcp-server/transports/auth/lib/withAuth.js +30 -0
  140. package/dist/mcp-server/transports/auth/lib/withAuth.js.map +1 -0
  141. package/dist/mcp-server/transports/auth/strategies/authStrategy.d.ts +18 -0
  142. package/dist/mcp-server/transports/auth/strategies/authStrategy.d.ts.map +1 -0
  143. package/dist/mcp-server/transports/auth/strategies/authStrategy.js +2 -0
  144. package/dist/mcp-server/transports/auth/strategies/authStrategy.js.map +1 -0
  145. package/dist/mcp-server/transports/auth/strategies/jwtStrategy.d.ts +14 -0
  146. package/dist/mcp-server/transports/auth/strategies/jwtStrategy.d.ts.map +1 -0
  147. package/dist/mcp-server/transports/auth/strategies/jwtStrategy.js +86 -0
  148. package/dist/mcp-server/transports/auth/strategies/jwtStrategy.js.map +1 -0
  149. package/dist/mcp-server/transports/auth/strategies/oauthStrategy.d.ts +14 -0
  150. package/dist/mcp-server/transports/auth/strategies/oauthStrategy.d.ts.map +1 -0
  151. package/dist/mcp-server/transports/auth/strategies/oauthStrategy.js +113 -0
  152. package/dist/mcp-server/transports/auth/strategies/oauthStrategy.js.map +1 -0
  153. package/dist/mcp-server/transports/http/httpErrorHandler.d.ts +25 -0
  154. package/dist/mcp-server/transports/http/httpErrorHandler.d.ts.map +1 -0
  155. package/dist/mcp-server/transports/http/httpErrorHandler.js +112 -0
  156. package/dist/mcp-server/transports/http/httpErrorHandler.js.map +1 -0
  157. package/dist/mcp-server/transports/http/httpTransport.d.ts +47 -0
  158. package/dist/mcp-server/transports/http/httpTransport.d.ts.map +1 -0
  159. package/dist/mcp-server/transports/http/httpTransport.js +396 -0
  160. package/dist/mcp-server/transports/http/httpTransport.js.map +1 -0
  161. package/dist/mcp-server/transports/http/httpTypes.d.ts +17 -0
  162. package/dist/mcp-server/transports/http/httpTypes.d.ts.map +1 -0
  163. package/dist/mcp-server/transports/http/httpTypes.js +2 -0
  164. package/dist/mcp-server/transports/http/httpTypes.js.map +1 -0
  165. package/dist/mcp-server/transports/http/protectedResourceMetadata.d.ts +21 -0
  166. package/dist/mcp-server/transports/http/protectedResourceMetadata.d.ts.map +1 -0
  167. package/dist/mcp-server/transports/http/protectedResourceMetadata.js +44 -0
  168. package/dist/mcp-server/transports/http/protectedResourceMetadata.js.map +1 -0
  169. package/dist/mcp-server/transports/http/sessionIdUtils.d.ts +33 -0
  170. package/dist/mcp-server/transports/http/sessionIdUtils.d.ts.map +1 -0
  171. package/dist/mcp-server/transports/http/sessionIdUtils.js +54 -0
  172. package/dist/mcp-server/transports/http/sessionIdUtils.js.map +1 -0
  173. package/dist/mcp-server/transports/http/sessionStore.d.ts +87 -0
  174. package/dist/mcp-server/transports/http/sessionStore.d.ts.map +1 -0
  175. package/dist/mcp-server/transports/http/sessionStore.js +209 -0
  176. package/dist/mcp-server/transports/http/sessionStore.js.map +1 -0
  177. package/dist/mcp-server/transports/manager.d.ts +22 -0
  178. package/dist/mcp-server/transports/manager.d.ts.map +1 -0
  179. package/dist/mcp-server/transports/manager.js +62 -0
  180. package/dist/mcp-server/transports/manager.js.map +1 -0
  181. package/dist/mcp-server/transports/stdio/stdioTransport.d.ts +44 -0
  182. package/dist/mcp-server/transports/stdio/stdioTransport.d.ts.map +1 -0
  183. package/dist/mcp-server/transports/stdio/stdioTransport.js +63 -0
  184. package/dist/mcp-server/transports/stdio/stdioTransport.js.map +1 -0
  185. package/dist/services/graph/core/GraphService.d.ts +205 -0
  186. package/dist/services/graph/core/GraphService.d.ts.map +1 -0
  187. package/dist/services/graph/core/GraphService.js +231 -0
  188. package/dist/services/graph/core/GraphService.js.map +1 -0
  189. package/dist/services/graph/core/IGraphProvider.d.ts +295 -0
  190. package/dist/services/graph/core/IGraphProvider.d.ts.map +1 -0
  191. package/dist/services/graph/core/IGraphProvider.js +8 -0
  192. package/dist/services/graph/core/IGraphProvider.js.map +1 -0
  193. package/dist/services/graph/types.d.ts +107 -0
  194. package/dist/services/graph/types.d.ts.map +1 -0
  195. package/dist/services/graph/types.js +8 -0
  196. package/dist/services/graph/types.js.map +1 -0
  197. package/dist/services/llm/core/ILlmProvider.d.ts +86 -0
  198. package/dist/services/llm/core/ILlmProvider.d.ts.map +1 -0
  199. package/dist/services/llm/core/ILlmProvider.js +2 -0
  200. package/dist/services/llm/core/ILlmProvider.js.map +1 -0
  201. package/dist/services/llm/providers/openrouter.provider.d.ts +187 -0
  202. package/dist/services/llm/providers/openrouter.provider.d.ts.map +1 -0
  203. package/dist/services/llm/providers/openrouter.provider.js +302 -0
  204. package/dist/services/llm/providers/openrouter.provider.js.map +1 -0
  205. package/dist/services/llm/types.d.ts +16 -0
  206. package/dist/services/llm/types.d.ts.map +1 -0
  207. package/dist/services/llm/types.js +9 -0
  208. package/dist/services/llm/types.js.map +1 -0
  209. package/dist/services/speech/core/ISpeechProvider.d.ts +92 -0
  210. package/dist/services/speech/core/ISpeechProvider.d.ts.map +1 -0
  211. package/dist/services/speech/core/ISpeechProvider.js +34 -0
  212. package/dist/services/speech/core/ISpeechProvider.js.map +1 -0
  213. package/dist/services/speech/core/SpeechService.d.ts +87 -0
  214. package/dist/services/speech/core/SpeechService.d.ts.map +1 -0
  215. package/dist/services/speech/core/SpeechService.js +135 -0
  216. package/dist/services/speech/core/SpeechService.js.map +1 -0
  217. package/dist/services/speech/providers/elevenlabs.provider.d.ts +77 -0
  218. package/dist/services/speech/providers/elevenlabs.provider.d.ts.map +1 -0
  219. package/dist/services/speech/providers/elevenlabs.provider.js +199 -0
  220. package/dist/services/speech/providers/elevenlabs.provider.js.map +1 -0
  221. package/dist/services/speech/providers/whisper.provider.d.ts +94 -0
  222. package/dist/services/speech/providers/whisper.provider.d.ts.map +1 -0
  223. package/dist/services/speech/providers/whisper.provider.js +240 -0
  224. package/dist/services/speech/providers/whisper.provider.js.map +1 -0
  225. package/dist/services/speech/types.d.ts +173 -0
  226. package/dist/services/speech/types.d.ts.map +1 -0
  227. package/dist/services/speech/types.js +8 -0
  228. package/dist/services/speech/types.js.map +1 -0
  229. package/dist/storage/core/IStorageProvider.d.ts +159 -0
  230. package/dist/storage/core/IStorageProvider.d.ts.map +1 -0
  231. package/dist/storage/core/IStorageProvider.js +2 -0
  232. package/dist/storage/core/IStorageProvider.js.map +1 -0
  233. package/dist/storage/core/StorageService.d.ts +22 -0
  234. package/dist/storage/core/StorageService.d.ts.map +1 -0
  235. package/dist/storage/core/StorageService.js +151 -0
  236. package/dist/storage/core/StorageService.js.map +1 -0
  237. package/dist/storage/core/storageFactory.d.ts +66 -0
  238. package/dist/storage/core/storageFactory.d.ts.map +1 -0
  239. package/dist/storage/core/storageFactory.js +122 -0
  240. package/dist/storage/core/storageFactory.js.map +1 -0
  241. package/dist/storage/core/storageValidation.d.ts +77 -0
  242. package/dist/storage/core/storageValidation.d.ts.map +1 -0
  243. package/dist/storage/core/storageValidation.js +303 -0
  244. package/dist/storage/core/storageValidation.js.map +1 -0
  245. package/dist/storage/providers/cloudflare/d1Provider.d.ts +94 -0
  246. package/dist/storage/providers/cloudflare/d1Provider.d.ts.map +1 -0
  247. package/dist/storage/providers/cloudflare/d1Provider.js +347 -0
  248. package/dist/storage/providers/cloudflare/d1Provider.js.map +1 -0
  249. package/dist/storage/providers/cloudflare/kvProvider.d.ts +21 -0
  250. package/dist/storage/providers/cloudflare/kvProvider.d.ts.map +1 -0
  251. package/dist/storage/providers/cloudflare/kvProvider.js +183 -0
  252. package/dist/storage/providers/cloudflare/kvProvider.js.map +1 -0
  253. package/dist/storage/providers/cloudflare/r2Provider.d.ts +28 -0
  254. package/dist/storage/providers/cloudflare/r2Provider.d.ts.map +1 -0
  255. package/dist/storage/providers/cloudflare/r2Provider.js +222 -0
  256. package/dist/storage/providers/cloudflare/r2Provider.js.map +1 -0
  257. package/dist/storage/providers/fileSystem/fileSystemProvider.d.ts +20 -0
  258. package/dist/storage/providers/fileSystem/fileSystemProvider.d.ts.map +1 -0
  259. package/dist/storage/providers/fileSystem/fileSystemProvider.js +282 -0
  260. package/dist/storage/providers/fileSystem/fileSystemProvider.js.map +1 -0
  261. package/dist/storage/providers/inMemory/inMemoryProvider.d.ts +21 -0
  262. package/dist/storage/providers/inMemory/inMemoryProvider.d.ts.map +1 -0
  263. package/dist/storage/providers/inMemory/inMemoryProvider.js +139 -0
  264. package/dist/storage/providers/inMemory/inMemoryProvider.js.map +1 -0
  265. package/dist/storage/providers/supabase/supabase.types.d.ts +49 -0
  266. package/dist/storage/providers/supabase/supabase.types.d.ts.map +1 -0
  267. package/dist/storage/providers/supabase/supabase.types.js +8 -0
  268. package/dist/storage/providers/supabase/supabase.types.js.map +1 -0
  269. package/dist/storage/providers/supabase/supabaseProvider.d.ts +24 -0
  270. package/dist/storage/providers/supabase/supabaseProvider.d.ts.map +1 -0
  271. package/dist/storage/providers/supabase/supabaseProvider.js +209 -0
  272. package/dist/storage/providers/supabase/supabaseProvider.js.map +1 -0
  273. package/dist/testing/index.d.ts +53 -0
  274. package/dist/testing/index.d.ts.map +1 -0
  275. package/dist/testing/index.js +132 -0
  276. package/dist/testing/index.js.map +1 -0
  277. package/dist/types-global/errors.d.ts +83 -0
  278. package/dist/types-global/errors.d.ts.map +1 -0
  279. package/dist/types-global/errors.js +113 -0
  280. package/dist/types-global/errors.js.map +1 -0
  281. package/dist/utils/formatting/diffFormatter.d.ts +227 -0
  282. package/dist/utils/formatting/diffFormatter.d.ts.map +1 -0
  283. package/dist/utils/formatting/diffFormatter.js +369 -0
  284. package/dist/utils/formatting/diffFormatter.js.map +1 -0
  285. package/dist/utils/formatting/index.d.ts +9 -0
  286. package/dist/utils/formatting/index.d.ts.map +1 -0
  287. package/dist/utils/formatting/index.js +9 -0
  288. package/dist/utils/formatting/index.js.map +1 -0
  289. package/dist/utils/formatting/markdownBuilder.d.ts +543 -0
  290. package/dist/utils/formatting/markdownBuilder.d.ts.map +1 -0
  291. package/dist/utils/formatting/markdownBuilder.js +674 -0
  292. package/dist/utils/formatting/markdownBuilder.js.map +1 -0
  293. package/dist/utils/formatting/tableFormatter.d.ts +261 -0
  294. package/dist/utils/formatting/tableFormatter.d.ts.map +1 -0
  295. package/dist/utils/formatting/tableFormatter.js +456 -0
  296. package/dist/utils/formatting/tableFormatter.js.map +1 -0
  297. package/dist/utils/formatting/treeFormatter.d.ts +344 -0
  298. package/dist/utils/formatting/treeFormatter.d.ts.map +1 -0
  299. package/dist/utils/formatting/treeFormatter.js +400 -0
  300. package/dist/utils/formatting/treeFormatter.js.map +1 -0
  301. package/dist/utils/internal/encoding.d.ts +42 -0
  302. package/dist/utils/internal/encoding.d.ts.map +1 -0
  303. package/dist/utils/internal/encoding.js +87 -0
  304. package/dist/utils/internal/encoding.js.map +1 -0
  305. package/dist/utils/internal/error-handler/errorHandler.d.ts +140 -0
  306. package/dist/utils/internal/error-handler/errorHandler.d.ts.map +1 -0
  307. package/dist/utils/internal/error-handler/errorHandler.js +318 -0
  308. package/dist/utils/internal/error-handler/errorHandler.js.map +1 -0
  309. package/dist/utils/internal/error-handler/helpers.d.ts +98 -0
  310. package/dist/utils/internal/error-handler/helpers.d.ts.map +1 -0
  311. package/dist/utils/internal/error-handler/helpers.js +214 -0
  312. package/dist/utils/internal/error-handler/helpers.js.map +1 -0
  313. package/dist/utils/internal/error-handler/mappings.d.ts +85 -0
  314. package/dist/utils/internal/error-handler/mappings.d.ts.map +1 -0
  315. package/dist/utils/internal/error-handler/mappings.js +234 -0
  316. package/dist/utils/internal/error-handler/mappings.js.map +1 -0
  317. package/dist/utils/internal/error-handler/types.d.ts +160 -0
  318. package/dist/utils/internal/error-handler/types.d.ts.map +1 -0
  319. package/dist/utils/internal/error-handler/types.js +6 -0
  320. package/dist/utils/internal/error-handler/types.js.map +1 -0
  321. package/dist/utils/internal/health.d.ts +60 -0
  322. package/dist/utils/internal/health.d.ts.map +1 -0
  323. package/dist/utils/internal/health.js +46 -0
  324. package/dist/utils/internal/health.js.map +1 -0
  325. package/dist/utils/internal/logger.d.ts +300 -0
  326. package/dist/utils/internal/logger.d.ts.map +1 -0
  327. package/dist/utils/internal/logger.js +573 -0
  328. package/dist/utils/internal/logger.js.map +1 -0
  329. package/dist/utils/internal/performance.d.ts +78 -0
  330. package/dist/utils/internal/performance.d.ts.map +1 -0
  331. package/dist/utils/internal/performance.js +227 -0
  332. package/dist/utils/internal/performance.js.map +1 -0
  333. package/dist/utils/internal/requestContext.d.ts +200 -0
  334. package/dist/utils/internal/requestContext.d.ts.map +1 -0
  335. package/dist/utils/internal/requestContext.js +163 -0
  336. package/dist/utils/internal/requestContext.js.map +1 -0
  337. package/dist/utils/internal/runtime.d.ts +49 -0
  338. package/dist/utils/internal/runtime.d.ts.map +1 -0
  339. package/dist/utils/internal/runtime.js +90 -0
  340. package/dist/utils/internal/runtime.js.map +1 -0
  341. package/dist/utils/internal/startupBanner.d.ts +23 -0
  342. package/dist/utils/internal/startupBanner.d.ts.map +1 -0
  343. package/dist/utils/internal/startupBanner.js +34 -0
  344. package/dist/utils/internal/startupBanner.js.map +1 -0
  345. package/dist/utils/metrics/tokenCounter.d.ts +97 -0
  346. package/dist/utils/metrics/tokenCounter.d.ts.map +1 -0
  347. package/dist/utils/metrics/tokenCounter.js +162 -0
  348. package/dist/utils/metrics/tokenCounter.js.map +1 -0
  349. package/dist/utils/network/fetchWithTimeout.d.ts +91 -0
  350. package/dist/utils/network/fetchWithTimeout.d.ts.map +1 -0
  351. package/dist/utils/network/fetchWithTimeout.js +305 -0
  352. package/dist/utils/network/fetchWithTimeout.js.map +1 -0
  353. package/dist/utils/pagination/pagination.d.ts +157 -0
  354. package/dist/utils/pagination/pagination.d.ts.map +1 -0
  355. package/dist/utils/pagination/pagination.js +191 -0
  356. package/dist/utils/pagination/pagination.js.map +1 -0
  357. package/dist/utils/parsing/csvParser.d.ts +84 -0
  358. package/dist/utils/parsing/csvParser.d.ts.map +1 -0
  359. package/dist/utils/parsing/csvParser.js +132 -0
  360. package/dist/utils/parsing/csvParser.js.map +1 -0
  361. package/dist/utils/parsing/dateParser.d.ts +103 -0
  362. package/dist/utils/parsing/dateParser.d.ts.map +1 -0
  363. package/dist/utils/parsing/dateParser.js +142 -0
  364. package/dist/utils/parsing/dateParser.js.map +1 -0
  365. package/dist/utils/parsing/frontmatterParser.d.ts +91 -0
  366. package/dist/utils/parsing/frontmatterParser.d.ts.map +1 -0
  367. package/dist/utils/parsing/frontmatterParser.js +163 -0
  368. package/dist/utils/parsing/frontmatterParser.js.map +1 -0
  369. package/dist/utils/parsing/index.d.ts +15 -0
  370. package/dist/utils/parsing/index.d.ts.map +1 -0
  371. package/dist/utils/parsing/index.js +15 -0
  372. package/dist/utils/parsing/index.js.map +1 -0
  373. package/dist/utils/parsing/jsonParser.d.ts +115 -0
  374. package/dist/utils/parsing/jsonParser.d.ts.map +1 -0
  375. package/dist/utils/parsing/jsonParser.js +177 -0
  376. package/dist/utils/parsing/jsonParser.js.map +1 -0
  377. package/dist/utils/parsing/pdfParser.d.ts +563 -0
  378. package/dist/utils/parsing/pdfParser.d.ts.map +1 -0
  379. package/dist/utils/parsing/pdfParser.js +775 -0
  380. package/dist/utils/parsing/pdfParser.js.map +1 -0
  381. package/dist/utils/parsing/thinkBlock.d.ts +31 -0
  382. package/dist/utils/parsing/thinkBlock.d.ts.map +1 -0
  383. package/dist/utils/parsing/thinkBlock.js +31 -0
  384. package/dist/utils/parsing/thinkBlock.js.map +1 -0
  385. package/dist/utils/parsing/xmlParser.d.ts +69 -0
  386. package/dist/utils/parsing/xmlParser.d.ts.map +1 -0
  387. package/dist/utils/parsing/xmlParser.js +140 -0
  388. package/dist/utils/parsing/xmlParser.js.map +1 -0
  389. package/dist/utils/parsing/yamlParser.d.ts +64 -0
  390. package/dist/utils/parsing/yamlParser.d.ts.map +1 -0
  391. package/dist/utils/parsing/yamlParser.js +129 -0
  392. package/dist/utils/parsing/yamlParser.js.map +1 -0
  393. package/dist/utils/scheduling/scheduler.d.ts +174 -0
  394. package/dist/utils/scheduling/scheduler.d.ts.map +1 -0
  395. package/dist/utils/scheduling/scheduler.js +248 -0
  396. package/dist/utils/scheduling/scheduler.js.map +1 -0
  397. package/dist/utils/security/idGenerator.d.ts +189 -0
  398. package/dist/utils/security/idGenerator.d.ts.map +1 -0
  399. package/dist/utils/security/idGenerator.js +301 -0
  400. package/dist/utils/security/idGenerator.js.map +1 -0
  401. package/dist/utils/security/index.d.ts +8 -0
  402. package/dist/utils/security/index.d.ts.map +1 -0
  403. package/dist/utils/security/index.js +8 -0
  404. package/dist/utils/security/index.js.map +1 -0
  405. package/dist/utils/security/rateLimiter.d.ts +171 -0
  406. package/dist/utils/security/rateLimiter.d.ts.map +1 -0
  407. package/dist/utils/security/rateLimiter.js +294 -0
  408. package/dist/utils/security/rateLimiter.js.map +1 -0
  409. package/dist/utils/security/sanitization.d.ts +430 -0
  410. package/dist/utils/security/sanitization.d.ts.map +1 -0
  411. package/dist/utils/security/sanitization.js +759 -0
  412. package/dist/utils/security/sanitization.js.map +1 -0
  413. package/dist/utils/telemetry/index.d.ts +12 -0
  414. package/dist/utils/telemetry/index.d.ts.map +1 -0
  415. package/dist/utils/telemetry/index.js +12 -0
  416. package/dist/utils/telemetry/index.js.map +1 -0
  417. package/dist/utils/telemetry/instrumentation.d.ts +62 -0
  418. package/dist/utils/telemetry/instrumentation.d.ts.map +1 -0
  419. package/dist/utils/telemetry/instrumentation.js +223 -0
  420. package/dist/utils/telemetry/instrumentation.js.map +1 -0
  421. package/dist/utils/telemetry/metrics.d.ts +170 -0
  422. package/dist/utils/telemetry/metrics.d.ts.map +1 -0
  423. package/dist/utils/telemetry/metrics.js +205 -0
  424. package/dist/utils/telemetry/metrics.js.map +1 -0
  425. package/dist/utils/telemetry/semconv.d.ts +147 -0
  426. package/dist/utils/telemetry/semconv.d.ts.map +1 -0
  427. package/dist/utils/telemetry/semconv.js +159 -0
  428. package/dist/utils/telemetry/semconv.js.map +1 -0
  429. package/dist/utils/telemetry/trace.d.ts +141 -0
  430. package/dist/utils/telemetry/trace.d.ts.map +1 -0
  431. package/dist/utils/telemetry/trace.js +193 -0
  432. package/dist/utils/telemetry/trace.js.map +1 -0
  433. package/dist/utils/types/guards.d.ts +209 -0
  434. package/dist/utils/types/guards.d.ts.map +1 -0
  435. package/dist/utils/types/guards.js +229 -0
  436. package/dist/utils/types/guards.js.map +1 -0
  437. package/dist/utils/types/index.d.ts +6 -0
  438. package/dist/utils/types/index.d.ts.map +1 -0
  439. package/dist/utils/types/index.js +6 -0
  440. package/dist/utils/types/index.js.map +1 -0
  441. package/dist/worker.d.ts +59 -0
  442. package/dist/worker.d.ts.map +1 -0
  443. package/dist/worker.js +216 -0
  444. package/dist/worker.js.map +1 -0
  445. package/package.json +377 -0
  446. package/skills/README.md +38 -0
  447. package/skills/add-export/SKILL.md +49 -0
  448. package/skills/add-prompt/SKILL.md +97 -0
  449. package/skills/add-provider/SKILL.md +53 -0
  450. package/skills/add-resource/SKILL.md +107 -0
  451. package/skills/add-service/SKILL.md +113 -0
  452. package/skills/add-tool/SKILL.md +110 -0
  453. package/skills/api-auth/SKILL.md +173 -0
  454. package/skills/api-config/SKILL.md +68 -0
  455. package/skills/api-context/SKILL.md +321 -0
  456. package/skills/api-errors/SKILL.md +146 -0
  457. package/skills/api-services/SKILL.md +24 -0
  458. package/skills/api-services/references/graph.md +124 -0
  459. package/skills/api-services/references/llm.md +46 -0
  460. package/skills/api-services/references/speech.md +72 -0
  461. package/skills/api-testing/SKILL.md +263 -0
  462. package/skills/api-utils/SKILL.md +106 -0
  463. package/skills/api-utils/references/formatting.md +237 -0
  464. package/skills/api-utils/references/parsing.md +263 -0
  465. package/skills/api-utils/references/security.md +226 -0
  466. package/skills/api-workers/SKILL.md +165 -0
  467. package/skills/devcheck/SKILL.md +31 -0
  468. package/skills/maintenance/SKILL.md +52 -0
  469. package/skills/migrate-mcp-ts-template/SKILL.md +131 -0
  470. package/skills/release/SKILL.md +67 -0
  471. package/skills/setup/SKILL.md +89 -0
  472. package/skills/walkthrough-init/SKILL.md +50 -0
  473. package/templates/.env.example +17 -0
  474. package/templates/AGENTS.md +113 -0
  475. package/templates/CLAUDE.md +113 -0
  476. package/templates/_tsconfig.json +33 -0
  477. package/templates/biome.template.json +43 -0
  478. package/templates/package.json +26 -0
  479. package/templates/src/index.ts +16 -0
  480. package/templates/src/mcp-server/prompts/definitions/echo.prompt.ts +19 -0
  481. package/templates/src/mcp-server/resources/definitions/echo.resource.ts +30 -0
  482. package/templates/src/mcp-server/tools/definitions/echo.tool.ts +24 -0
  483. package/templates/vitest.config.ts +12 -0
  484. package/tsconfig.base.json +44 -0
  485. package/vitest.config.base.ts +38 -0
@@ -0,0 +1,205 @@
1
+ /**
2
+ * @fileoverview Graph service orchestrator.
3
+ * Manages graph database operations with provider abstraction.
4
+ * @module src/services/graph/core/GraphService
5
+ */
6
+ import type { RequestContext } from '../../../utils/internal/requestContext.js';
7
+ import type { GraphStats } from '../types.js';
8
+ import type { Edge, GraphPath, IGraphProvider, PathOptions, RelateOptions, TraversalOptions, TraversalResult } from './IGraphProvider.js';
9
+ /**
10
+ * Provider-agnostic service for graph database operations.
11
+ *
12
+ * @remarks
13
+ * Wraps an {@link IGraphProvider} implementation and adds request-scoped debug
14
+ * logging around every operation. All graph I/O — relationship management,
15
+ * traversal, pathfinding, edge queries, statistics, and health checks — is
16
+ * delegated to the injected provider.
17
+ *
18
+ * @example
19
+ * ```ts
20
+ * import { GraphService } from './GraphService.js';
21
+ * import { MockGraphProvider } from '../providers/mock/MockGraphProvider.js';
22
+ *
23
+ * const graphService = new GraphService(new MockGraphProvider());
24
+ *
25
+ * // Create a relationship
26
+ * const edge = await graphService.relate(
27
+ * 'user:alice',
28
+ * 'follows',
29
+ * 'user:bob',
30
+ * context,
31
+ * { data: { since: '2025-01-01' } },
32
+ * );
33
+ *
34
+ * // Traverse the graph
35
+ * const result = await graphService.traverse('user:alice', context, {
36
+ * maxDepth: 2,
37
+ * edgeTypes: ['follows'],
38
+ * });
39
+ * ```
40
+ */
41
+ export declare class GraphService {
42
+ private readonly provider;
43
+ constructor(provider: IGraphProvider);
44
+ /**
45
+ * Return the underlying {@link IGraphProvider} instance.
46
+ * Useful for accessing provider-specific extensions not exposed by this service.
47
+ *
48
+ * @returns The active graph provider
49
+ *
50
+ * @example
51
+ * ```ts
52
+ * const provider = graphService.getProvider();
53
+ * console.log(provider.name); // e.g. 'mock'
54
+ * ```
55
+ */
56
+ getProvider(): IGraphProvider;
57
+ /**
58
+ * Create a directed relationship edge between two vertices.
59
+ *
60
+ * @param from - ID of the source vertex
61
+ * @param edgeTable - Table (type) name for the edge (e.g. `'follows'`)
62
+ * @param to - ID of the target vertex
63
+ * @param context - Request context used for correlated logging
64
+ * @param options - Optional edge payload and duplicate-handling behaviour
65
+ * @returns The newly created edge
66
+ * @throws {Error} If either vertex does not exist or the provider rejects a duplicate
67
+ *
68
+ * @example
69
+ * ```ts
70
+ * const edge = await graphService.relate('user:alice', 'follows', 'user:bob', context, {
71
+ * data: { since: '2025-01-01' },
72
+ * });
73
+ * ```
74
+ */
75
+ relate(from: string, edgeTable: string, to: string, context: RequestContext, options?: RelateOptions): Promise<Edge>;
76
+ /**
77
+ * Delete a relationship edge by its ID.
78
+ *
79
+ * @param edgeId - ID of the edge to remove
80
+ * @param context - Request context used for correlated logging
81
+ * @returns `true` if the edge was found and deleted, `false` if it did not exist
82
+ * @throws {Error} If the provider encounters a storage error
83
+ *
84
+ * @example
85
+ * ```ts
86
+ * const deleted = await graphService.unrelate('follows:1', context);
87
+ * ```
88
+ */
89
+ unrelate(edgeId: string, context: RequestContext): Promise<boolean>;
90
+ /**
91
+ * Traverse the graph outward (or inward/both) from a starting vertex.
92
+ *
93
+ * @param startVertexId - ID of the vertex to begin traversal from
94
+ * @param context - Request context used for correlated logging
95
+ * @param options - Direction, depth limit, edge/vertex type filters, and WHERE expression
96
+ * @returns All discovered paths and the resolved start vertex
97
+ * @throws {Error} If the start vertex does not exist or the provider query fails
98
+ *
99
+ * @example
100
+ * ```ts
101
+ * const result = await graphService.traverse('user:alice', context, {
102
+ * maxDepth: 2,
103
+ * edgeTypes: ['follows'],
104
+ * direction: 'out',
105
+ * });
106
+ * console.log(`Found ${result.paths.length} paths`);
107
+ * ```
108
+ */
109
+ traverse(startVertexId: string, context: RequestContext, options?: TraversalOptions): Promise<TraversalResult>;
110
+ /**
111
+ * Find the lowest-cost path between two vertices using the specified algorithm.
112
+ *
113
+ * @param from - ID of the source vertex
114
+ * @param to - ID of the target vertex
115
+ * @param context - Request context used for correlated logging
116
+ * @param options - Algorithm selection, depth limit, and optional weight function
117
+ * @returns The shortest path, or `null` if no path exists within the constraints
118
+ * @throws {Error} If the provider encounters a storage or query error
119
+ *
120
+ * @example
121
+ * ```ts
122
+ * const path = await graphService.shortestPath('user:alice', 'user:charlie', context, {
123
+ * algorithm: 'bfs',
124
+ * maxLength: 4,
125
+ * });
126
+ * if (path) console.log(`${path.vertices.length} hops`);
127
+ * ```
128
+ */
129
+ shortestPath(from: string, to: string, context: RequestContext, options?: PathOptions): Promise<GraphPath | null>;
130
+ /**
131
+ * Get all outgoing edges originating from a vertex.
132
+ *
133
+ * @param vertexId - ID of the source vertex
134
+ * @param context - Request context used for correlated logging
135
+ * @param edgeTypes - When provided, only edges belonging to these tables are returned
136
+ * @returns Array of matching outgoing edges, or an empty array if none
137
+ * @throws {Error} If the provider encounters a storage or query error
138
+ *
139
+ * @example
140
+ * ```ts
141
+ * const edges = await graphService.getOutgoingEdges('user:alice', context, ['follows']);
142
+ * ```
143
+ */
144
+ getOutgoingEdges(vertexId: string, context: RequestContext, edgeTypes?: string[]): Promise<Edge[]>;
145
+ /**
146
+ * Get all incoming edges directed at a vertex.
147
+ *
148
+ * @param vertexId - ID of the target vertex
149
+ * @param context - Request context used for correlated logging
150
+ * @param edgeTypes - When provided, only edges belonging to these tables are returned
151
+ * @returns Array of matching incoming edges, or an empty array if none
152
+ * @throws {Error} If the provider encounters a storage or query error
153
+ *
154
+ * @example
155
+ * ```ts
156
+ * const edges = await graphService.getIncomingEdges('user:bob', context, ['follows']);
157
+ * ```
158
+ */
159
+ getIncomingEdges(vertexId: string, context: RequestContext, edgeTypes?: string[]): Promise<Edge[]>;
160
+ /**
161
+ * Determine whether any path exists between two vertices without returning it.
162
+ * More efficient than `shortestPath` when only reachability is needed.
163
+ *
164
+ * @param from - ID of the source vertex
165
+ * @param to - ID of the target vertex
166
+ * @param context - Request context used for correlated logging
167
+ * @param maxDepth - Maximum hop count to search. Unbounded when omitted.
168
+ * @returns `true` if at least one path exists within the depth limit
169
+ * @throws {Error} If the provider encounters a storage or query error
170
+ *
171
+ * @example
172
+ * ```ts
173
+ * const connected = await graphService.pathExists('user:alice', 'user:charlie', context, 3);
174
+ * ```
175
+ */
176
+ pathExists(from: string, to: string, context: RequestContext, maxDepth?: number): Promise<boolean>;
177
+ /**
178
+ * Compute aggregate statistics about the current graph.
179
+ *
180
+ * @param context - Request context used for correlated logging
181
+ * @returns Snapshot of vertex/edge counts and per-type breakdowns
182
+ * @throws {Error} If the provider cannot compute statistics
183
+ *
184
+ * @example
185
+ * ```ts
186
+ * const stats = await graphService.getStats(context);
187
+ * console.log(`${stats.vertexCount} vertices, avg degree ${stats.avgDegree}`);
188
+ * ```
189
+ */
190
+ getStats(context: RequestContext): Promise<GraphStats>;
191
+ /**
192
+ * Perform a liveness check on the underlying graph provider.
193
+ *
194
+ * @returns `true` if the provider is reachable and operational, `false` otherwise
195
+ *
196
+ * @example
197
+ * ```ts
198
+ * if (!(await graphService.healthCheck())) {
199
+ * throw new Error('Graph provider is unhealthy');
200
+ * }
201
+ * ```
202
+ */
203
+ healthCheck(): Promise<boolean>;
204
+ }
205
+ //# sourceMappingURL=GraphService.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"GraphService.d.ts","sourceRoot":"","sources":["../../../../src/services/graph/core/GraphService.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EACV,IAAI,EACJ,SAAS,EACT,cAAc,EACd,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,cAAc;IAIrD;;;;;;;;;;;OAWG;IACH,WAAW,IAAI,cAAc;IAI7B;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC;IAMhB;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAMzE;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,CACZ,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC;IAM3B;;;;;;;;;;;;;;;;;;OAkBG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAM5B;;;;;;;;;;;;;OAaG;IACG,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,EACvB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,IAAI,EAAE,CAAC;IAIlB;;;;;;;;;;;;;OAaG;IACG,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,EACvB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,IAAI,EAAE,CAAC;IAIlB;;;;;;;;;;;;;;;OAeG;IACG,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,cAAc,EACvB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAInB;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAK5D;;;;;;;;;;;OAWG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAGtC"}
@@ -0,0 +1,231 @@
1
+ /**
2
+ * @fileoverview Graph service orchestrator.
3
+ * Manages graph database operations with provider abstraction.
4
+ * @module src/services/graph/core/GraphService
5
+ */
6
+ import { logger } from '../../../utils/internal/logger.js';
7
+ /**
8
+ * Provider-agnostic service for graph database operations.
9
+ *
10
+ * @remarks
11
+ * Wraps an {@link IGraphProvider} implementation and adds request-scoped debug
12
+ * logging around every operation. All graph I/O — relationship management,
13
+ * traversal, pathfinding, edge queries, statistics, and health checks — is
14
+ * delegated to the injected provider.
15
+ *
16
+ * @example
17
+ * ```ts
18
+ * import { GraphService } from './GraphService.js';
19
+ * import { MockGraphProvider } from '../providers/mock/MockGraphProvider.js';
20
+ *
21
+ * const graphService = new GraphService(new MockGraphProvider());
22
+ *
23
+ * // Create a relationship
24
+ * const edge = await graphService.relate(
25
+ * 'user:alice',
26
+ * 'follows',
27
+ * 'user:bob',
28
+ * context,
29
+ * { data: { since: '2025-01-01' } },
30
+ * );
31
+ *
32
+ * // Traverse the graph
33
+ * const result = await graphService.traverse('user:alice', context, {
34
+ * maxDepth: 2,
35
+ * edgeTypes: ['follows'],
36
+ * });
37
+ * ```
38
+ */
39
+ export class GraphService {
40
+ provider;
41
+ constructor(provider) {
42
+ this.provider = provider;
43
+ logger.info(`Graph service initialized with provider: ${provider.name}`);
44
+ }
45
+ /**
46
+ * Return the underlying {@link IGraphProvider} instance.
47
+ * Useful for accessing provider-specific extensions not exposed by this service.
48
+ *
49
+ * @returns The active graph provider
50
+ *
51
+ * @example
52
+ * ```ts
53
+ * const provider = graphService.getProvider();
54
+ * console.log(provider.name); // e.g. 'mock'
55
+ * ```
56
+ */
57
+ getProvider() {
58
+ return this.provider;
59
+ }
60
+ /**
61
+ * Create a directed relationship edge between two vertices.
62
+ *
63
+ * @param from - ID of the source vertex
64
+ * @param edgeTable - Table (type) name for the edge (e.g. `'follows'`)
65
+ * @param to - ID of the target vertex
66
+ * @param context - Request context used for correlated logging
67
+ * @param options - Optional edge payload and duplicate-handling behaviour
68
+ * @returns The newly created edge
69
+ * @throws {Error} If either vertex does not exist or the provider rejects a duplicate
70
+ *
71
+ * @example
72
+ * ```ts
73
+ * const edge = await graphService.relate('user:alice', 'follows', 'user:bob', context, {
74
+ * data: { since: '2025-01-01' },
75
+ * });
76
+ * ```
77
+ */
78
+ async relate(from, edgeTable, to, context, options) {
79
+ logger.debug(`[GraphService] Creating relationship: ${from} -[${edgeTable}]-> ${to}`, context);
80
+ return await this.provider.relate(from, edgeTable, to, context, options);
81
+ }
82
+ /**
83
+ * Delete a relationship edge by its ID.
84
+ *
85
+ * @param edgeId - ID of the edge to remove
86
+ * @param context - Request context used for correlated logging
87
+ * @returns `true` if the edge was found and deleted, `false` if it did not exist
88
+ * @throws {Error} If the provider encounters a storage error
89
+ *
90
+ * @example
91
+ * ```ts
92
+ * const deleted = await graphService.unrelate('follows:1', context);
93
+ * ```
94
+ */
95
+ async unrelate(edgeId, context) {
96
+ logger.debug(`[GraphService] Deleting relationship: ${edgeId}`, context);
97
+ return await this.provider.unrelate(edgeId, context);
98
+ }
99
+ /**
100
+ * Traverse the graph outward (or inward/both) from a starting vertex.
101
+ *
102
+ * @param startVertexId - ID of the vertex to begin traversal from
103
+ * @param context - Request context used for correlated logging
104
+ * @param options - Direction, depth limit, edge/vertex type filters, and WHERE expression
105
+ * @returns All discovered paths and the resolved start vertex
106
+ * @throws {Error} If the start vertex does not exist or the provider query fails
107
+ *
108
+ * @example
109
+ * ```ts
110
+ * const result = await graphService.traverse('user:alice', context, {
111
+ * maxDepth: 2,
112
+ * edgeTypes: ['follows'],
113
+ * direction: 'out',
114
+ * });
115
+ * console.log(`Found ${result.paths.length} paths`);
116
+ * ```
117
+ */
118
+ async traverse(startVertexId, context, options) {
119
+ logger.debug(`[GraphService] Traversing from: ${startVertexId}`, context);
120
+ return await this.provider.traverse(startVertexId, context, options);
121
+ }
122
+ /**
123
+ * Find the lowest-cost path between two vertices using the specified algorithm.
124
+ *
125
+ * @param from - ID of the source vertex
126
+ * @param to - ID of the target vertex
127
+ * @param context - Request context used for correlated logging
128
+ * @param options - Algorithm selection, depth limit, and optional weight function
129
+ * @returns The shortest path, or `null` if no path exists within the constraints
130
+ * @throws {Error} If the provider encounters a storage or query error
131
+ *
132
+ * @example
133
+ * ```ts
134
+ * const path = await graphService.shortestPath('user:alice', 'user:charlie', context, {
135
+ * algorithm: 'bfs',
136
+ * maxLength: 4,
137
+ * });
138
+ * if (path) console.log(`${path.vertices.length} hops`);
139
+ * ```
140
+ */
141
+ async shortestPath(from, to, context, options) {
142
+ logger.debug(`[GraphService] Finding shortest path: ${from} -> ${to}`, context);
143
+ return await this.provider.shortestPath(from, to, context, options);
144
+ }
145
+ /**
146
+ * Get all outgoing edges originating from a vertex.
147
+ *
148
+ * @param vertexId - ID of the source vertex
149
+ * @param context - Request context used for correlated logging
150
+ * @param edgeTypes - When provided, only edges belonging to these tables are returned
151
+ * @returns Array of matching outgoing edges, or an empty array if none
152
+ * @throws {Error} If the provider encounters a storage or query error
153
+ *
154
+ * @example
155
+ * ```ts
156
+ * const edges = await graphService.getOutgoingEdges('user:alice', context, ['follows']);
157
+ * ```
158
+ */
159
+ async getOutgoingEdges(vertexId, context, edgeTypes) {
160
+ return await this.provider.getOutgoingEdges(vertexId, context, edgeTypes);
161
+ }
162
+ /**
163
+ * Get all incoming edges directed at a vertex.
164
+ *
165
+ * @param vertexId - ID of the target vertex
166
+ * @param context - Request context used for correlated logging
167
+ * @param edgeTypes - When provided, only edges belonging to these tables are returned
168
+ * @returns Array of matching incoming edges, or an empty array if none
169
+ * @throws {Error} If the provider encounters a storage or query error
170
+ *
171
+ * @example
172
+ * ```ts
173
+ * const edges = await graphService.getIncomingEdges('user:bob', context, ['follows']);
174
+ * ```
175
+ */
176
+ async getIncomingEdges(vertexId, context, edgeTypes) {
177
+ return await this.provider.getIncomingEdges(vertexId, context, edgeTypes);
178
+ }
179
+ /**
180
+ * Determine whether any path exists between two vertices without returning it.
181
+ * More efficient than `shortestPath` when only reachability is needed.
182
+ *
183
+ * @param from - ID of the source vertex
184
+ * @param to - ID of the target vertex
185
+ * @param context - Request context used for correlated logging
186
+ * @param maxDepth - Maximum hop count to search. Unbounded when omitted.
187
+ * @returns `true` if at least one path exists within the depth limit
188
+ * @throws {Error} If the provider encounters a storage or query error
189
+ *
190
+ * @example
191
+ * ```ts
192
+ * const connected = await graphService.pathExists('user:alice', 'user:charlie', context, 3);
193
+ * ```
194
+ */
195
+ async pathExists(from, to, context, maxDepth) {
196
+ return await this.provider.pathExists(from, to, context, maxDepth);
197
+ }
198
+ /**
199
+ * Compute aggregate statistics about the current graph.
200
+ *
201
+ * @param context - Request context used for correlated logging
202
+ * @returns Snapshot of vertex/edge counts and per-type breakdowns
203
+ * @throws {Error} If the provider cannot compute statistics
204
+ *
205
+ * @example
206
+ * ```ts
207
+ * const stats = await graphService.getStats(context);
208
+ * console.log(`${stats.vertexCount} vertices, avg degree ${stats.avgDegree}`);
209
+ * ```
210
+ */
211
+ async getStats(context) {
212
+ logger.debug('[GraphService] Getting graph statistics', context);
213
+ return await this.provider.getStats(context);
214
+ }
215
+ /**
216
+ * Perform a liveness check on the underlying graph provider.
217
+ *
218
+ * @returns `true` if the provider is reachable and operational, `false` otherwise
219
+ *
220
+ * @example
221
+ * ```ts
222
+ * if (!(await graphService.healthCheck())) {
223
+ * throw new Error('Graph provider is unhealthy');
224
+ * }
225
+ * ```
226
+ */
227
+ async healthCheck() {
228
+ return await this.provider.healthCheck();
229
+ }
230
+ }
231
+ //# sourceMappingURL=GraphService.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"GraphService.js","sourceRoot":"","sources":["../../../../src/services/graph/core/GraphService.ts"],"names":[],"mappings":"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"}