@plyaz/core 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (240) hide show
  1. package/README.md +248 -183
  2. package/dist/adapters/index.d.ts +16 -0
  3. package/dist/adapters/index.d.ts.map +1 -0
  4. package/dist/adapters/nestjs.d.ts +79 -0
  5. package/dist/adapters/nestjs.d.ts.map +1 -0
  6. package/dist/adapters/nextjs.d.ts +28 -0
  7. package/dist/adapters/nextjs.d.ts.map +1 -0
  8. package/dist/backend/example/example.controller.d.ts +121 -0
  9. package/dist/backend/example/example.controller.d.ts.map +1 -0
  10. package/dist/backend/example/example.module.d.ts +29 -0
  11. package/dist/backend/example/example.module.d.ts.map +1 -0
  12. package/dist/backend/example/index.d.ts +8 -0
  13. package/dist/backend/example/index.d.ts.map +1 -0
  14. package/dist/backend/featureFlags/FeatureFlagDomainService.d.ts +150 -0
  15. package/dist/backend/featureFlags/FeatureFlagDomainService.d.ts.map +1 -0
  16. package/dist/backend/featureFlags/config/feature-flag.config.d.ts +28 -50
  17. package/dist/backend/featureFlags/config/feature-flag.config.d.ts.map +1 -1
  18. package/dist/backend/featureFlags/config/validation.d.ts +6 -6
  19. package/dist/backend/featureFlags/config/validation.d.ts.map +1 -1
  20. package/dist/backend/featureFlags/feature-flag.controller.d.ts +14 -55
  21. package/dist/backend/featureFlags/feature-flag.controller.d.ts.map +1 -1
  22. package/dist/backend/featureFlags/feature-flag.module.d.ts +36 -43
  23. package/dist/backend/featureFlags/feature-flag.module.d.ts.map +1 -1
  24. package/dist/backend/featureFlags/guards/feature-flag.guard.d.ts +16 -2
  25. package/dist/backend/featureFlags/guards/feature-flag.guard.d.ts.map +1 -1
  26. package/dist/backend/featureFlags/index.d.ts +6 -7
  27. package/dist/backend/featureFlags/index.d.ts.map +1 -1
  28. package/dist/backend/featureFlags/interceptors/error-handling-interceptor.d.ts.map +1 -1
  29. package/dist/backend/featureFlags/interceptors/feature-flag-logging-interceptor.d.ts.map +1 -1
  30. package/dist/backend/featureFlags/middleware/feature-flag-middleware.d.ts +6 -11
  31. package/dist/backend/featureFlags/middleware/feature-flag-middleware.d.ts.map +1 -1
  32. package/dist/backend/index.d.ts +5 -0
  33. package/dist/backend/index.d.ts.map +1 -1
  34. package/dist/base/cache/CacheKeyBuilder.d.ts +115 -0
  35. package/dist/base/cache/CacheKeyBuilder.d.ts.map +1 -0
  36. package/dist/base/cache/index.d.ts +1 -0
  37. package/dist/base/cache/index.d.ts.map +1 -1
  38. package/dist/base/cache/strategies/redis.d.ts.map +1 -1
  39. package/dist/base/observability/BaseAdapter.d.ts +79 -0
  40. package/dist/base/observability/BaseAdapter.d.ts.map +1 -0
  41. package/dist/base/observability/CompositeAdapter.d.ts +72 -0
  42. package/dist/base/observability/CompositeAdapter.d.ts.map +1 -0
  43. package/dist/base/observability/DatadogAdapter.d.ts +117 -0
  44. package/dist/base/observability/DatadogAdapter.d.ts.map +1 -0
  45. package/dist/base/observability/LoggerAdapter.d.ts +54 -0
  46. package/dist/base/observability/LoggerAdapter.d.ts.map +1 -0
  47. package/dist/base/observability/ObservabilityService.d.ts +160 -0
  48. package/dist/base/observability/ObservabilityService.d.ts.map +1 -0
  49. package/dist/base/observability/index.d.ts +17 -0
  50. package/dist/base/observability/index.d.ts.map +1 -0
  51. package/dist/domain/base/BaseBackendDomainService.d.ts +528 -0
  52. package/dist/domain/base/BaseBackendDomainService.d.ts.map +1 -0
  53. package/dist/domain/base/BaseDomainService.d.ts +284 -0
  54. package/dist/domain/base/BaseDomainService.d.ts.map +1 -0
  55. package/dist/domain/base/BaseFrontendDomainService.d.ts +493 -0
  56. package/dist/domain/base/BaseFrontendDomainService.d.ts.map +1 -0
  57. package/dist/domain/base/BaseMapper.d.ts +100 -0
  58. package/dist/domain/base/BaseMapper.d.ts.map +1 -0
  59. package/dist/domain/base/BaseValidator.d.ts +105 -0
  60. package/dist/domain/base/BaseValidator.d.ts.map +1 -0
  61. package/dist/domain/base/index.d.ts +10 -0
  62. package/dist/domain/base/index.d.ts.map +1 -0
  63. package/dist/domain/example/BackendExampleDomainService.d.ts +257 -0
  64. package/dist/domain/example/BackendExampleDomainService.d.ts.map +1 -0
  65. package/dist/domain/example/FrontendExampleDomainService.d.ts +164 -0
  66. package/dist/domain/example/FrontendExampleDomainService.d.ts.map +1 -0
  67. package/dist/domain/example/index.d.ts +10 -0
  68. package/dist/domain/example/index.d.ts.map +1 -0
  69. package/dist/domain/example/mappers/ExampleMapper.d.ts +67 -0
  70. package/dist/domain/example/mappers/ExampleMapper.d.ts.map +1 -0
  71. package/dist/domain/example/validators/ExampleValidator.d.ts +33 -0
  72. package/dist/domain/example/validators/ExampleValidator.d.ts.map +1 -0
  73. package/dist/domain/featureFlags/FrontendFeatureFlagDomainService.d.ts +86 -0
  74. package/dist/domain/featureFlags/FrontendFeatureFlagDomainService.d.ts.map +1 -0
  75. package/dist/domain/featureFlags/index.d.ts +10 -5
  76. package/dist/domain/featureFlags/index.d.ts.map +1 -1
  77. package/dist/domain/featureFlags/mappers/FeatureFlagMapper.d.ts +72 -0
  78. package/dist/domain/featureFlags/mappers/FeatureFlagMapper.d.ts.map +1 -0
  79. package/dist/domain/featureFlags/mappers/index.d.ts +8 -0
  80. package/dist/domain/featureFlags/mappers/index.d.ts.map +1 -0
  81. package/dist/domain/featureFlags/module.d.ts +20 -0
  82. package/dist/domain/featureFlags/module.d.ts.map +1 -0
  83. package/dist/domain/featureFlags/provider.d.ts +40 -1
  84. package/dist/domain/featureFlags/provider.d.ts.map +1 -1
  85. package/dist/domain/featureFlags/providers/api.d.ts +59 -34
  86. package/dist/domain/featureFlags/providers/api.d.ts.map +1 -1
  87. package/dist/domain/featureFlags/providers/database.d.ts +54 -47
  88. package/dist/domain/featureFlags/providers/database.d.ts.map +1 -1
  89. package/dist/domain/featureFlags/providers/factory.d.ts +50 -33
  90. package/dist/domain/featureFlags/providers/factory.d.ts.map +1 -1
  91. package/dist/domain/featureFlags/providers/file.d.ts +48 -1
  92. package/dist/domain/featureFlags/providers/file.d.ts.map +1 -1
  93. package/dist/domain/featureFlags/providers/memory.d.ts +32 -6
  94. package/dist/domain/featureFlags/providers/memory.d.ts.map +1 -1
  95. package/dist/domain/featureFlags/providers/redis.d.ts +6 -1
  96. package/dist/domain/featureFlags/providers/redis.d.ts.map +1 -1
  97. package/dist/domain/featureFlags/service.d.ts +112 -0
  98. package/dist/domain/featureFlags/service.d.ts.map +1 -0
  99. package/dist/domain/index.d.ts +2 -0
  100. package/dist/domain/index.d.ts.map +1 -1
  101. package/dist/engine/featureFlags/engine.d.ts +8 -0
  102. package/dist/engine/featureFlags/engine.d.ts.map +1 -1
  103. package/dist/entry-backend.d.ts +26 -0
  104. package/dist/entry-backend.d.ts.map +1 -0
  105. package/dist/entry-backend.js +15455 -0
  106. package/dist/entry-backend.js.map +1 -0
  107. package/dist/entry-backend.mjs +15339 -0
  108. package/dist/entry-backend.mjs.map +1 -0
  109. package/dist/entry-frontend.d.ts +23 -0
  110. package/dist/entry-frontend.d.ts.map +1 -0
  111. package/dist/entry-frontend.js +11340 -0
  112. package/dist/entry-frontend.js.map +1 -0
  113. package/dist/entry-frontend.mjs +11278 -0
  114. package/dist/entry-frontend.mjs.map +1 -0
  115. package/dist/events/CoreEventManager.d.ts +116 -0
  116. package/dist/events/CoreEventManager.d.ts.map +1 -0
  117. package/dist/events/index.d.ts +27 -0
  118. package/dist/events/index.d.ts.map +1 -0
  119. package/dist/frontend/base/index.d.ts +8 -0
  120. package/dist/frontend/base/index.d.ts.map +1 -0
  121. package/dist/frontend/components/InitializationError.d.ts +25 -0
  122. package/dist/frontend/components/InitializationError.d.ts.map +1 -0
  123. package/dist/frontend/components/InitializationLoading.d.ts +22 -0
  124. package/dist/frontend/components/InitializationLoading.d.ts.map +1 -0
  125. package/dist/frontend/components/index.d.ts +9 -0
  126. package/dist/frontend/components/index.d.ts.map +1 -0
  127. package/dist/frontend/example/index.d.ts +9 -0
  128. package/dist/frontend/example/index.d.ts.map +1 -0
  129. package/dist/frontend/featureFlags/index.d.ts +28 -7
  130. package/dist/frontend/featureFlags/index.d.ts.map +1 -1
  131. package/dist/frontend/index.d.ts +4 -0
  132. package/dist/frontend/index.d.ts.map +1 -1
  133. package/dist/frontend/providers/ApiProvider.d.ts +2 -2
  134. package/dist/frontend/providers/ApiProvider.d.ts.map +1 -1
  135. package/dist/frontend/providers/PlyazProvider.d.ts +305 -0
  136. package/dist/frontend/providers/PlyazProvider.d.ts.map +1 -0
  137. package/dist/frontend/providers/index.d.ts +1 -0
  138. package/dist/frontend/providers/index.d.ts.map +1 -1
  139. package/dist/frontend/store/feature-flags.d.ts +63 -0
  140. package/dist/frontend/store/feature-flags.d.ts.map +1 -0
  141. package/dist/frontend/store/index.d.ts +14 -0
  142. package/dist/frontend/store/index.d.ts.map +1 -0
  143. package/dist/frontend/store/integrations.d.ts +36 -0
  144. package/dist/frontend/store/integrations.d.ts.map +1 -0
  145. package/dist/frontend/store/service-accessors.d.ts +78 -0
  146. package/dist/frontend/store/service-accessors.d.ts.map +1 -0
  147. package/dist/index.d.ts +5 -2
  148. package/dist/index.d.ts.map +1 -1
  149. package/dist/index.js +15262 -0
  150. package/dist/index.js.map +1 -0
  151. package/dist/index.mjs +13667 -4861
  152. package/dist/index.mjs.map +1 -1
  153. package/dist/init/CoreInitializer.d.ts +583 -0
  154. package/dist/init/CoreInitializer.d.ts.map +1 -0
  155. package/dist/init/ServiceRegistry.d.ts +256 -0
  156. package/dist/init/ServiceRegistry.d.ts.map +1 -0
  157. package/dist/init/index.d.ts +14 -0
  158. package/dist/init/index.d.ts.map +1 -0
  159. package/dist/init/nestjs/CoreModule.d.ts +63 -0
  160. package/dist/init/nestjs/CoreModule.d.ts.map +1 -0
  161. package/dist/init/nestjs/index.d.ts +5 -0
  162. package/dist/init/nestjs/index.d.ts.map +1 -0
  163. package/dist/init/nestjs/index.js +9234 -0
  164. package/dist/init/nestjs/index.js.map +1 -0
  165. package/dist/init/nestjs/index.mjs +9230 -0
  166. package/dist/init/nestjs/index.mjs.map +1 -0
  167. package/dist/init/react.d.ts +33 -0
  168. package/dist/init/react.d.ts.map +1 -0
  169. package/dist/models/example/ExampleRepository.d.ts +166 -0
  170. package/dist/models/example/ExampleRepository.d.ts.map +1 -0
  171. package/dist/models/example/index.d.ts +7 -0
  172. package/dist/models/example/index.d.ts.map +1 -0
  173. package/dist/models/featureFlags/FeatureFlagRepository.d.ts +161 -0
  174. package/dist/models/featureFlags/FeatureFlagRepository.d.ts.map +1 -0
  175. package/dist/models/featureFlags/index.d.ts +7 -0
  176. package/dist/models/featureFlags/index.d.ts.map +1 -0
  177. package/dist/models/index.d.ts +9 -0
  178. package/dist/models/index.d.ts.map +1 -0
  179. package/dist/services/ApiClientService.d.ts +92 -4
  180. package/dist/services/ApiClientService.d.ts.map +1 -1
  181. package/dist/services/CacheService.d.ts +176 -0
  182. package/dist/services/CacheService.d.ts.map +1 -0
  183. package/dist/services/DbService.d.ts +393 -0
  184. package/dist/services/DbService.d.ts.map +1 -0
  185. package/dist/services/NotificationService.d.ts +153 -0
  186. package/dist/services/NotificationService.d.ts.map +1 -0
  187. package/dist/services/StorageService.d.ts +146 -0
  188. package/dist/services/StorageService.d.ts.map +1 -0
  189. package/dist/services/index.d.ts +4 -0
  190. package/dist/services/index.d.ts.map +1 -1
  191. package/dist/utils/common/id.d.ts +83 -0
  192. package/dist/utils/common/id.d.ts.map +1 -0
  193. package/dist/utils/common/index.d.ts +2 -0
  194. package/dist/utils/common/index.d.ts.map +1 -1
  195. package/dist/utils/common/object.d.ts +70 -0
  196. package/dist/utils/common/object.d.ts.map +1 -0
  197. package/dist/utils/featureFlags/conditions.d.ts.map +1 -1
  198. package/dist/utils/featureFlags/context.d.ts +0 -1
  199. package/dist/utils/featureFlags/context.d.ts.map +1 -1
  200. package/dist/utils/index.d.ts +1 -0
  201. package/dist/utils/index.d.ts.map +1 -1
  202. package/dist/utils/mapperUtils.d.ts +38 -0
  203. package/dist/utils/mapperUtils.d.ts.map +1 -0
  204. package/dist/utils/runtime.d.ts +15 -0
  205. package/dist/utils/runtime.d.ts.map +1 -0
  206. package/dist/version.d.ts +24 -0
  207. package/dist/version.d.ts.map +1 -0
  208. package/dist/web_app/auth/add_user.d.ts +2 -2
  209. package/dist/web_app/auth/add_user.d.ts.map +1 -1
  210. package/dist/web_app/auth/update_user.d.ts +1 -1
  211. package/dist/web_app/auth/update_user.d.ts.map +1 -1
  212. package/package.json +89 -15
  213. package/dist/backend/featureFlags/database/connection.d.ts +0 -321
  214. package/dist/backend/featureFlags/database/connection.d.ts.map +0 -1
  215. package/dist/backend/featureFlags/database/repository.d.ts +0 -518
  216. package/dist/backend/featureFlags/database/repository.d.ts.map +0 -1
  217. package/dist/backend/featureFlags/feature-flag.repository.d.ts +0 -85
  218. package/dist/backend/featureFlags/feature-flag.repository.d.ts.map +0 -1
  219. package/dist/backend/featureFlags/feature-flag.service.d.ts +0 -264
  220. package/dist/backend/featureFlags/feature-flag.service.d.ts.map +0 -1
  221. package/dist/frontend/featureFlags/hooks/useFeatureFlag.d.ts +0 -103
  222. package/dist/frontend/featureFlags/hooks/useFeatureFlag.d.ts.map +0 -1
  223. package/dist/frontend/featureFlags/hooks/useFeatureFlagActions.d.ts +0 -35
  224. package/dist/frontend/featureFlags/hooks/useFeatureFlagActions.d.ts.map +0 -1
  225. package/dist/frontend/featureFlags/hooks/useFeatureFlagHelpers.d.ts +0 -55
  226. package/dist/frontend/featureFlags/hooks/useFeatureFlagHelpers.d.ts.map +0 -1
  227. package/dist/frontend/featureFlags/hooks/useFeatureFlagProvider.d.ts +0 -57
  228. package/dist/frontend/featureFlags/hooks/useFeatureFlagProvider.d.ts.map +0 -1
  229. package/dist/frontend/featureFlags/providers/FeatureFlagProvider.d.ts +0 -99
  230. package/dist/frontend/featureFlags/providers/FeatureFlagProvider.d.ts.map +0 -1
  231. package/dist/frontend/featureFlags/providers/FeatureFlagProviderHelpers.d.ts +0 -31
  232. package/dist/frontend/featureFlags/providers/FeatureFlagProviderHelpers.d.ts.map +0 -1
  233. package/dist/frontend/featureFlags/providers/types.d.ts +0 -21
  234. package/dist/frontend/featureFlags/providers/types.d.ts.map +0 -1
  235. package/dist/index.cjs +0 -6435
  236. package/dist/index.cjs.map +0 -1
  237. package/dist/utils/db/databaseService.d.ts +0 -6
  238. package/dist/utils/db/databaseService.d.ts.map +0 -1
  239. package/dist/utils/db/index.d.ts +0 -2
  240. package/dist/utils/db/index.d.ts.map +0 -1
@@ -0,0 +1,176 @@
1
+ /**
2
+ * CacheService - Singleton Cache Manager
3
+ *
4
+ * @description Manages cache instance for the entire application using a singleton pattern.
5
+ * This service wraps the CacheManager from @plyaz/core/base/cache and provides a centralized
6
+ * way to initialize and access caching across all backend services.
7
+ *
8
+ * **Architecture:**
9
+ * - Supports multiple strategies: Memory (in-process), Redis (distributed)
10
+ * - Configurable TTL, key prefixing, and strategy-specific options
11
+ * - Singleton pattern ensures single cache instance across application
12
+ *
13
+ * **Strategy Configuration:**
14
+ * - **Memory**: In-process LRU cache, no external dependencies
15
+ * - **Redis**: Distributed cache using ioredis, requires Redis server
16
+ *
17
+ * **Required Environment Variables (Redis):**
18
+ * - REDIS_URL: Redis connection string (e.g., redis://localhost:6379)
19
+ * - Or REDIS_HOST, REDIS_PORT, REDIS_PASSWORD for individual config
20
+ *
21
+ * @example Using with Core.initialize() (Recommended)
22
+ * ```typescript
23
+ * import { Core } from '@plyaz/core';
24
+ *
25
+ * await Core.initialize({
26
+ * envPath: '.env',
27
+ * cache: {
28
+ * strategy: 'memory',
29
+ * isEnabled: true,
30
+ * ttl: 300, // 5 minutes default
31
+ * },
32
+ * });
33
+ *
34
+ * // Access via Core.cache
35
+ * const cache = Core.cache.getCacheManager();
36
+ * await cache.set('user:123', userData, 600); // 10 minutes TTL
37
+ * const cached = await cache.get('user:123');
38
+ * ```
39
+ *
40
+ * @example With Redis Strategy
41
+ * ```typescript
42
+ * await Core.initialize({
43
+ * envPath: '.env',
44
+ * cache: {
45
+ * strategy: 'redis',
46
+ * isEnabled: true,
47
+ * ttl: 300,
48
+ * prefix: 'myapp',
49
+ * redis: {
50
+ * url: process.env.REDIS_URL,
51
+ * // Or individual options:
52
+ * // host: process.env.REDIS_HOST,
53
+ * // port: parseInt(process.env.REDIS_PORT),
54
+ * // password: process.env.REDIS_PASSWORD,
55
+ * },
56
+ * },
57
+ * });
58
+ * ```
59
+ *
60
+ * @example Direct Usage
61
+ * ```typescript
62
+ * import { CacheService } from '@plyaz/core/services';
63
+ *
64
+ * await CacheService.initialize({
65
+ * strategy: 'memory',
66
+ * isEnabled: true,
67
+ * ttl: 300,
68
+ * });
69
+ *
70
+ * const cache = CacheService.getInstance().getCacheManager();
71
+ * await cache.set('key', value);
72
+ * ```
73
+ *
74
+ * @example Skip Cache (Disable Caching)
75
+ * ```typescript
76
+ * await Core.initialize({
77
+ * skipCache: true, // Cache will not be initialized
78
+ * });
79
+ * ```
80
+ *
81
+ * @fileoverview Cache service singleton
82
+ * @module services/CacheService
83
+ */
84
+ import { CacheManager } from '../base/cache';
85
+ import type { CoreCacheConfig } from '@plyaz/types/core';
86
+ /**
87
+ * Singleton service for managing application-wide cache
88
+ *
89
+ * Provides centralized access to cache functionality across all backend services.
90
+ * Automatically integrates with BaseBackendDomainService when initialized.
91
+ */
92
+ export declare class CacheService {
93
+ /** Singleton instance */
94
+ private static instance;
95
+ /** Cache manager instance */
96
+ private cacheManager;
97
+ /** Configuration used to initialize cache */
98
+ private config;
99
+ /** Logger instance */
100
+ private logger;
101
+ /** Private constructor to enforce singleton */
102
+ private constructor();
103
+ /**
104
+ * Initialize the cache service with configuration
105
+ *
106
+ * @param config - Cache configuration
107
+ * @throws {CorePackageError} If already initialized or config is invalid
108
+ *
109
+ * @example
110
+ * ```typescript
111
+ * await CacheService.initialize({
112
+ * strategy: 'redis',
113
+ * isEnabled: true,
114
+ * ttl: 300,
115
+ * prefix: 'app',
116
+ * redis: { url: process.env.REDIS_URL },
117
+ * });
118
+ * ```
119
+ */
120
+ static initialize(config: CoreCacheConfig): Promise<void>;
121
+ /**
122
+ * Get the singleton instance
123
+ *
124
+ * @throws {CorePackageError} If not initialized
125
+ * @returns CacheService singleton instance
126
+ *
127
+ * @example
128
+ * ```typescript
129
+ * const cacheService = CacheService.getInstance();
130
+ * const cache = cacheService.getCacheManager();
131
+ * ```
132
+ */
133
+ static getInstance(): CacheService;
134
+ /**
135
+ * Get the cache manager instance
136
+ *
137
+ * @throws {CorePackageError} If cache not initialized
138
+ * @returns CacheManager instance
139
+ *
140
+ * @example
141
+ * ```typescript
142
+ * const cache = CacheService.getInstance().getCacheManager();
143
+ * await cache.set('user:123', userData);
144
+ * const user = await cache.get('user:123');
145
+ * ```
146
+ */
147
+ getCacheManager(): CacheManager;
148
+ /**
149
+ * Get current cache configuration
150
+ *
151
+ * @returns Current cache configuration or null if not initialized
152
+ */
153
+ getConfig(): CoreCacheConfig | null;
154
+ /**
155
+ * Check if cache is initialized and enabled
156
+ *
157
+ * @returns True if cache is ready to use
158
+ */
159
+ isInitialized(): boolean;
160
+ /**
161
+ * Reset the cache service (useful for testing)
162
+ *
163
+ * @internal
164
+ */
165
+ static reset(): void;
166
+ /**
167
+ * Validate cache configuration
168
+ *
169
+ * @param config - Configuration to validate
170
+ * @throws {CorePackageError} If configuration is invalid
171
+ * @private
172
+ */
173
+ private validateConfig;
174
+ }
175
+ export declare const getCacheService: () => CacheService;
176
+ //# sourceMappingURL=CacheService.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"CacheService.d.ts","sourceRoot":"","sources":["../../src/services/CacheService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,yBAAyB;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA6B;IAEpD,6BAA6B;IAC7B,OAAO,CAAC,YAAY,CAA6B;IAEjD,6CAA6C;IAC7C,OAAO,CAAC,MAAM,CAAgC;IAE9C,sBAAsB;IACtB,OAAO,CAAC,MAAM,CAA+C;IAE7D,+CAA+C;IAC/C,OAAO;IAEP;;;;;;;;;;;;;;;;OAgBG;WACU,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IA0C/D;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,WAAW,IAAI,YAAY;IAUlC;;;;;;;;;;;;OAYG;IACH,eAAe,IAAI,YAAY;IAU/B;;;;OAIG;IACH,SAAS,IAAI,eAAe,GAAG,IAAI;IAInC;;;;OAIG;IACH,aAAa,IAAI,OAAO;IAIxB;;;;OAIG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAWpB;;;;;;OAMG;IAEH,OAAO,CAAC,cAAc;CA6BvB;AAGD,eAAO,MAAM,eAAe,QAAO,YAA0C,CAAC"}
@@ -0,0 +1,393 @@
1
+ /**
2
+ * DbService - Singleton Database Connection Manager
3
+ *
4
+ * @description Manages database connections for the entire application using a singleton pattern.
5
+ * This service wraps @plyaz/db and provides a centralized way to initialize and access
6
+ * the database across all domains (feature flags, users, campaigns, backoffice, etc.).
7
+ *
8
+ * **Architecture:**
9
+ * - Uses `createDatabaseService()` from @plyaz/db which builds an adapter chain
10
+ * - Supports Drizzle (direct PostgreSQL), Supabase (REST API), or raw SQL adapters
11
+ * - Extension layers: Encryption → SoftDelete → Caching → Audit → ReadReplica
12
+ *
13
+ * **Adapter Configuration:**
14
+ * - **Drizzle**: Requires `connectionString` (PostgreSQL URL)
15
+ * - **Supabase**: Requires `supabaseUrl`, `supabaseServiceKey`, `supabaseAnonKey`
16
+ * - **SQL**: Requires `connectionString`
17
+ *
18
+ * **Required Environment Variables (Drizzle with Supabase):**
19
+ * - DATABASE_URL: PostgreSQL connection string (from Supabase Dashboard > Database > URI)
20
+ *
21
+ * **Required Environment Variables (Supabase REST API):**
22
+ * - SUPABASE_URL: Your Supabase project URL
23
+ * - SUPABASE_SERVICE_ROLE_KEY: Service role key for admin operations
24
+ * - SUPABASE_ANON_PUBLIC_KEY: Anonymous key for public operations
25
+ *
26
+ * @example Using with Core.initialize() (Recommended)
27
+ * ```typescript
28
+ * import { Core } from '@plyaz/core';
29
+ *
30
+ * // Core.initialize() handles loading env and passing to DbService
31
+ * await Core.initialize({
32
+ * envPath: '.env',
33
+ * db: {
34
+ * adapter: 'sql',
35
+ * cache: { enabled: true, ttl: 60 },
36
+ * },
37
+ * });
38
+ *
39
+ * // Access via Core.db
40
+ * const db = Core.db.getDatabase();
41
+ * const result = await db.list('users', { pagination: { limit: 10, offset: 0 } });
42
+ * ```
43
+ *
44
+ * @example Direct Usage (requires explicit config)
45
+ * ```typescript
46
+ * // Direct usage requires explicit connectionString
47
+ * await DbService.initialize({
48
+ * adapter: 'drizzle',
49
+ * drizzle: {
50
+ * connectionString: 'postgresql://user:pass@localhost:5432/db',
51
+ * poolSize: 20,
52
+ * },
53
+ * });
54
+ * ```
55
+ *
56
+ * @example With Extensions
57
+ * ```typescript
58
+ * await Core.initialize({
59
+ * envPath: '.env',
60
+ * db: {
61
+ * adapter: 'drizzle',
62
+ * softDelete: {
63
+ * enabled: true,
64
+ * field: 'deleted_at',
65
+ * excludeTables: ['audit_logs', 'feature_flag_evaluations'],
66
+ * },
67
+ * cache: {
68
+ * enabled: true,
69
+ * provider: 'memory',
70
+ * ttl: 300,
71
+ * },
72
+ * audit: {
73
+ * enabled: true,
74
+ * retentionDays: 90,
75
+ * },
76
+ * },
77
+ * });
78
+ * ```
79
+ *
80
+ * @example Using with BaseRepository
81
+ * ```typescript
82
+ * import { BaseRepository } from '@plyaz/db';
83
+ * import { DbService } from '@plyaz/core';
84
+ *
85
+ * class UserRepository extends BaseRepository<User> {
86
+ * constructor() {
87
+ * super(DbService.getInstance().getDatabase(), 'users');
88
+ * }
89
+ * }
90
+ * ```
91
+ *
92
+ * @module services
93
+ */
94
+ import { type DatabaseServiceInterface, type Transaction } from '@plyaz/types/db';
95
+ /**
96
+ * Default fields to encrypt per table
97
+ * Contains sensitive PII and financial data that should be encrypted at rest
98
+ *
99
+ * @see docs/db-schemas/dbdiagram_schema.dbml for field definitions
100
+ */
101
+ export declare const DEFAULT_ENCRYPTION_FIELDS: Record<string, string[]>;
102
+ export type { CoreDbServiceConfig } from '@plyaz/types/core';
103
+ import type { CoreDbServiceConfig as DbServiceConfig } from '@plyaz/types/core';
104
+ /**
105
+ * Complete table registry from database migrations
106
+ * Maps logical table names to their ID columns
107
+ *
108
+ * @see docs/db-schemas/migrations/ for schema definitions
109
+ * @see docs/db-schemas/dbdiagram_schema.dbml for full schema
110
+ */
111
+ /**
112
+ * TABLE_REGISTRY - Custom ID Column and Schema Registry
113
+ *
114
+ * ONLY register tables with:
115
+ * 1. Custom ID columns (anything other than 'id')
116
+ * 2. Custom database schemas (anything other than 'public')
117
+ *
118
+ * Tables with standard 'id' column in 'public' schema do NOT need registration.
119
+ * You can also override ID column and schema per-query using OperationConfig.
120
+ *
121
+ * Schema can be defined in the table key or in the config object (or both):
122
+ * - 'schema.table': { idColumn: 'key' } ← Schema in key only
123
+ * - 'schema.table': { idColumn: 'key', schema: 'schema' } ← Redundant but allowed
124
+ * - 'schema.table': {} ← Empty config, schema in key
125
+ * - 'table': { idColumn: 'key', schema: 'schema' } ← Schema in config only
126
+ *
127
+ * @example
128
+ * ```typescript
129
+ * // Using registry
130
+ * await db.get('feature_flags', 'my-flag-key'); // Uses 'key' column from registry
131
+ *
132
+ * // Per-query override
133
+ * await db.get('custom_table', 'some-key', { idColumn: 'custom_id' });
134
+ *
135
+ * // Schema override
136
+ * await db.get('logs', '123', { schema: 'logging' });
137
+ * ```
138
+ */
139
+ export declare const TABLE_REGISTRY: Record<string, {
140
+ idColumn?: string;
141
+ schema?: string;
142
+ }>;
143
+ /**
144
+ * DbService - Singleton Database Connection Manager
145
+ *
146
+ * Provides centralized database connection management for all domains.
147
+ * Uses @plyaz/db under the hood with configurable adapters and extensions.
148
+ */
149
+ export declare class DbService {
150
+ private static instance;
151
+ private databaseService;
152
+ private namedAdapters;
153
+ private config;
154
+ private initialized;
155
+ private constructor();
156
+ /**
157
+ * Emits a database error event via CoreEventManager.
158
+ * Called when database operations fail to integrate with global error handling.
159
+ *
160
+ * @param error - The error that occurred
161
+ * @param operation - The operation that failed (e.g., 'transaction', 'query', 'healthCheck')
162
+ * @param table - Optional table name involved in the operation
163
+ * @param query - Optional query string that failed
164
+ * @param recoverable - Whether the error is recoverable (default: false)
165
+ */
166
+ private emitDatabaseError;
167
+ /**
168
+ * Gets the singleton instance of DbService
169
+ *
170
+ * @returns {DbService} The singleton instance
171
+ */
172
+ static getInstance(): DbService;
173
+ /**
174
+ * Checks if the database service has been initialized
175
+ *
176
+ * @returns {boolean} True if initialized
177
+ */
178
+ static isInitialized(): boolean;
179
+ /**
180
+ * Resets the database service by closing connections and clearing the singleton instance
181
+ *
182
+ * @description Properly closes the database connection and clears the singleton.
183
+ * Useful for testing or when you need to reinitialize with different configuration.
184
+ *
185
+ * @example
186
+ * ```typescript
187
+ * await DbService.reset();
188
+ * await DbService.initialize({ adapter: 'sql', ... });
189
+ * ```
190
+ */
191
+ static reset(): Promise<void>;
192
+ /**
193
+ * Initializes the database connection
194
+ *
195
+ * @description Sets up the database connection using the provided configuration
196
+ * or environment variables. This method is idempotent - calling it multiple
197
+ * times won't create additional connections.
198
+ *
199
+ * **Environment Variables:**
200
+ * - `DATABASE_URL` - PostgreSQL connection string (for sql/drizzle adapters)
201
+ * - `ENCRYPTION_KEY` - 32-byte encryption key for field encryption (optional)
202
+ * - `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_ANON_PUBLIC_KEY` - For supabase adapter
203
+ *
204
+ * **Encryption:** If `ENCRYPTION_KEY` env is set, encryption is auto-enabled
205
+ * using `DEFAULT_ENCRYPTION_FIELDS`. Override via config.encryption.
206
+ *
207
+ * @param {DbServiceConfig} [config] - Optional configuration
208
+ * @returns {Promise<DbService>} The initialized DbService instance
209
+ * @throws {DatabasePackageError} When configuration is invalid or connection fails
210
+ *
211
+ * @example
212
+ * ```typescript
213
+ * // Minimal - uses DATABASE_URL env, auto-enables encryption if ENCRYPTION_KEY set
214
+ * await DbService.initialize();
215
+ *
216
+ * // With explicit encryption
217
+ * await DbService.initialize({
218
+ * adapter: 'sql',
219
+ * encryption: {
220
+ * enabled: true,
221
+ * key: 'your-32-byte-encryption-key-here!!',
222
+ * fields: DEFAULT_ENCRYPTION_FIELDS,
223
+ * },
224
+ * });
225
+ *
226
+ * // Or via Core.initialize() with env:
227
+ * await Core.initialize({
228
+ * env: { ENCRYPTION_KEY: '...' },
229
+ * db: { adapter: 'sql' },
230
+ * });
231
+ * ```
232
+ */
233
+ /** Build encryption config from user config */
234
+ private static buildEncryptionConfig;
235
+ /** Merge user config with defaults */
236
+ private static mergeConfig;
237
+ /** Initialize named adapters */
238
+ private initializeNamedAdapters;
239
+ static initialize(config?: DbServiceConfig): Promise<DbService>;
240
+ /**
241
+ * Builds the DatabaseServiceConfig based on the adapter type
242
+ * @private
243
+ */
244
+ /** Builds adapter-specific config based on adapter type */
245
+ private buildAdapterConfig;
246
+ /** Builds soft delete extension config */
247
+ private buildSoftDeleteExtension;
248
+ /** Builds cache extension config */
249
+ private buildCacheExtension;
250
+ /** Builds audit extension config */
251
+ private buildAuditExtension;
252
+ /** Builds encryption extension config */
253
+ private buildEncryptionExtension;
254
+ private buildDatabaseConfig;
255
+ /**
256
+ * Builds Drizzle adapter configuration
257
+ * @private
258
+ */
259
+ private buildDrizzleConfig;
260
+ /**
261
+ * Builds Supabase adapter configuration
262
+ * @private
263
+ */
264
+ private buildSupabaseConfig;
265
+ /**
266
+ * Builds SQL adapter configuration
267
+ * @private
268
+ */
269
+ private buildSqlConfig;
270
+ /**
271
+ * Builds table ID column mappings from TABLE_REGISTRY
272
+ * @private
273
+ * @returns Record of table names to ID column names
274
+ */
275
+ private buildTableIdColumns;
276
+ /**
277
+ * Gets the initialized database service instance
278
+ *
279
+ * @param {string} [adapterName] - Optional named adapter to use instead of default
280
+ * @returns {DatabaseServiceInterface} The database service instance
281
+ * @throws {DatabasePackageError} When database is not initialized or named adapter not found
282
+ */
283
+ getDatabase(adapterName?: string): DatabaseServiceInterface;
284
+ /**
285
+ * Gets a named adapter by name
286
+ *
287
+ * @param {string} name - The name of the adapter
288
+ * @returns {DatabaseServiceInterface} The named adapter instance
289
+ * @throws {DatabasePackageError} When adapter not found
290
+ */
291
+ getAdapter(name: string): DatabaseServiceInterface;
292
+ /**
293
+ * Lists all available named adapters
294
+ *
295
+ * @returns {string[]} Array of adapter names
296
+ */
297
+ getAvailableAdapters(): string[];
298
+ /**
299
+ * Executes a database transaction with automatic rollback on failure
300
+ *
301
+ * @template T The return type of the transaction callback
302
+ * @param {Function} callback - Function that receives transaction object
303
+ * @returns {Promise<T>} The result of the transaction callback
304
+ * @throws {DatabasePackageError} When transaction fails
305
+ */
306
+ transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
307
+ /**
308
+ * Sets audit context for subsequent operations
309
+ *
310
+ * @param context - Audit context (userId, requestId, etc.)
311
+ */
312
+ setAuditContext(context: {
313
+ userId?: string;
314
+ requestId?: string;
315
+ ipAddress?: string;
316
+ userAgent?: string;
317
+ }): Promise<void>;
318
+ /**
319
+ * Performs a health check on the database connection
320
+ *
321
+ * @returns Health check result
322
+ */
323
+ healthCheck(): Promise<{
324
+ isHealthy: boolean;
325
+ responseTime?: number;
326
+ error?: string;
327
+ }>;
328
+ /**
329
+ * Gets the table registry with all known tables and their ID columns
330
+ *
331
+ * @returns The complete table registry
332
+ */
333
+ static getTableRegistry(): typeof TABLE_REGISTRY;
334
+ /**
335
+ * Gets ID column for a specific table
336
+ *
337
+ * @param tableName - Name of the table
338
+ * @returns ID column name or 'id' as default
339
+ */
340
+ static getTableIdColumn(tableName: string): string;
341
+ /**
342
+ * Reinitializes the database connection with new config
343
+ *
344
+ * @param {DbServiceConfig} [config] - New configuration
345
+ * @returns {Promise<DbService>} The reinitialized DbService instance
346
+ */
347
+ static reinitialize(config?: DbServiceConfig): Promise<DbService>;
348
+ /**
349
+ * Closes the database connection and cleans up resources
350
+ */
351
+ close(): Promise<void>;
352
+ /**
353
+ * Gets the current configuration
354
+ *
355
+ * @returns {DbServiceConfig | null} Current config or null if not initialized
356
+ */
357
+ getConfig(): DbServiceConfig | null;
358
+ /**
359
+ * Gets the current adapter type
360
+ *
361
+ * @returns The adapter type or null if not initialized
362
+ */
363
+ getAdapterType(): 'drizzle' | 'supabase' | 'sql' | null;
364
+ /**
365
+ * Creates a dedicated database service instance (NOT the singleton)
366
+ *
367
+ * Use this when you need an isolated database connection with its own configuration
368
+ * that doesn't affect or get affected by the shared singleton instance.
369
+ *
370
+ * @param config - Database service configuration
371
+ * @returns Promise that resolves to a new dedicated DbService instance
372
+ *
373
+ * @example
374
+ * ```typescript
375
+ * // Create a dedicated instance for analytics database
376
+ * const analyticsDb = await DbService.createInstance({
377
+ * adapter: 'sql',
378
+ * sql: { connectionString: process.env.ANALYTICS_DB_URL },
379
+ * cache: { enabled: false }, // No caching for analytics
380
+ * });
381
+ *
382
+ * // This instance is independent from DbService.getInstance()
383
+ * const data = await analyticsDb.getDatabase().list('events');
384
+ *
385
+ * // Clean up when done
386
+ * await analyticsDb.close();
387
+ * ```
388
+ */
389
+ static createInstance(config: DbServiceConfig): Promise<DbService>;
390
+ }
391
+ /** Type alias for DbService instance (use for type-only imports to avoid bundling) */
392
+ export type DbServiceInstance = DbService;
393
+ //# sourceMappingURL=DbService.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"DbService.d.ts","sourceRoot":"","sources":["../../src/services/DbService.ts"],"names":[],"mappings":"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"}