alepha 0.12.1 → 0.13.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 (198) hide show
  1. package/dist/api-notifications/index.d.ts +111 -111
  2. package/dist/api-users/index.d.ts +1240 -1240
  3. package/dist/api-verifications/index.d.ts +94 -94
  4. package/dist/cli/{dist-Sz2EXvQX.cjs → dist-Dl9Vl7Ur.js} +17 -13
  5. package/dist/cli/{dist-BBPjuQ56.js.map → dist-Dl9Vl7Ur.js.map} +1 -1
  6. package/dist/cli/index.d.ts +3 -11
  7. package/dist/cli/index.js +106 -74
  8. package/dist/cli/index.js.map +1 -1
  9. package/dist/email/index.js +71 -73
  10. package/dist/email/index.js.map +1 -1
  11. package/dist/orm/index.d.ts +1 -1
  12. package/dist/orm/index.js.map +1 -1
  13. package/dist/queue/index.d.ts +4 -4
  14. package/dist/redis/index.d.ts +10 -10
  15. package/dist/retry/index.d.ts +1 -1
  16. package/dist/retry/index.js +2 -2
  17. package/dist/retry/index.js.map +1 -1
  18. package/dist/scheduler/index.d.ts +6 -6
  19. package/dist/server/index.js +1 -1
  20. package/dist/server/index.js.map +1 -1
  21. package/dist/server-auth/index.d.ts +193 -193
  22. package/dist/server-health/index.d.ts +17 -17
  23. package/dist/server-links/index.d.ts +34 -34
  24. package/dist/server-metrics/index.js +170 -174
  25. package/dist/server-metrics/index.js.map +1 -1
  26. package/dist/server-security/index.d.ts +9 -9
  27. package/dist/vite/index.js +4 -5
  28. package/dist/vite/index.js.map +1 -1
  29. package/dist/websocket/index.d.ts +7 -7
  30. package/package.json +52 -103
  31. package/src/cli/apps/AlephaPackageBuilderCli.ts +7 -2
  32. package/src/cli/assets/appRouterTs.ts +9 -0
  33. package/src/cli/assets/indexHtml.ts +2 -1
  34. package/src/cli/assets/mainBrowserTs.ts +10 -0
  35. package/src/cli/commands/CoreCommands.ts +6 -5
  36. package/src/cli/commands/DrizzleCommands.ts +65 -57
  37. package/src/cli/commands/VerifyCommands.ts +1 -1
  38. package/src/cli/services/ProjectUtils.ts +44 -38
  39. package/src/orm/providers/DrizzleKitProvider.ts +1 -1
  40. package/src/retry/descriptors/$retry.ts +5 -3
  41. package/src/server/providers/NodeHttpServerProvider.ts +1 -1
  42. package/src/vite/helpers/boot.ts +3 -3
  43. package/dist/api-files/index.cjs +0 -1293
  44. package/dist/api-files/index.cjs.map +0 -1
  45. package/dist/api-files/index.d.cts +0 -829
  46. package/dist/api-jobs/index.cjs +0 -274
  47. package/dist/api-jobs/index.cjs.map +0 -1
  48. package/dist/api-jobs/index.d.cts +0 -654
  49. package/dist/api-notifications/index.cjs +0 -380
  50. package/dist/api-notifications/index.cjs.map +0 -1
  51. package/dist/api-notifications/index.d.cts +0 -289
  52. package/dist/api-parameters/index.cjs +0 -66
  53. package/dist/api-parameters/index.cjs.map +0 -1
  54. package/dist/api-parameters/index.d.cts +0 -84
  55. package/dist/api-users/index.cjs +0 -6009
  56. package/dist/api-users/index.cjs.map +0 -1
  57. package/dist/api-users/index.d.cts +0 -4740
  58. package/dist/api-verifications/index.cjs +0 -407
  59. package/dist/api-verifications/index.cjs.map +0 -1
  60. package/dist/api-verifications/index.d.cts +0 -207
  61. package/dist/batch/index.cjs +0 -408
  62. package/dist/batch/index.cjs.map +0 -1
  63. package/dist/batch/index.d.cts +0 -330
  64. package/dist/bin/index.cjs +0 -17
  65. package/dist/bin/index.cjs.map +0 -1
  66. package/dist/bin/index.d.cts +0 -1
  67. package/dist/bucket/index.cjs +0 -303
  68. package/dist/bucket/index.cjs.map +0 -1
  69. package/dist/bucket/index.d.cts +0 -355
  70. package/dist/cache/index.cjs +0 -241
  71. package/dist/cache/index.cjs.map +0 -1
  72. package/dist/cache/index.d.cts +0 -202
  73. package/dist/cache-redis/index.cjs +0 -84
  74. package/dist/cache-redis/index.cjs.map +0 -1
  75. package/dist/cache-redis/index.d.cts +0 -40
  76. package/dist/cli/chunk-DSlc6foC.cjs +0 -43
  77. package/dist/cli/dist-BBPjuQ56.js +0 -2778
  78. package/dist/cli/dist-Sz2EXvQX.cjs.map +0 -1
  79. package/dist/cli/index.cjs +0 -1241
  80. package/dist/cli/index.cjs.map +0 -1
  81. package/dist/cli/index.d.cts +0 -422
  82. package/dist/command/index.cjs +0 -693
  83. package/dist/command/index.cjs.map +0 -1
  84. package/dist/command/index.d.cts +0 -340
  85. package/dist/core/index.cjs +0 -2264
  86. package/dist/core/index.cjs.map +0 -1
  87. package/dist/core/index.d.cts +0 -1927
  88. package/dist/datetime/index.cjs +0 -318
  89. package/dist/datetime/index.cjs.map +0 -1
  90. package/dist/datetime/index.d.cts +0 -145
  91. package/dist/email/index.cjs +0 -10874
  92. package/dist/email/index.cjs.map +0 -1
  93. package/dist/email/index.d.cts +0 -186
  94. package/dist/fake/index.cjs +0 -34641
  95. package/dist/fake/index.cjs.map +0 -1
  96. package/dist/fake/index.d.cts +0 -74
  97. package/dist/file/index.cjs +0 -1212
  98. package/dist/file/index.cjs.map +0 -1
  99. package/dist/file/index.d.cts +0 -698
  100. package/dist/lock/index.cjs +0 -226
  101. package/dist/lock/index.cjs.map +0 -1
  102. package/dist/lock/index.d.cts +0 -361
  103. package/dist/lock-redis/index.cjs +0 -113
  104. package/dist/lock-redis/index.cjs.map +0 -1
  105. package/dist/lock-redis/index.d.cts +0 -24
  106. package/dist/logger/index.cjs +0 -521
  107. package/dist/logger/index.cjs.map +0 -1
  108. package/dist/logger/index.d.cts +0 -281
  109. package/dist/orm/index.cjs +0 -2986
  110. package/dist/orm/index.cjs.map +0 -1
  111. package/dist/orm/index.d.cts +0 -2213
  112. package/dist/queue/index.cjs +0 -1044
  113. package/dist/queue/index.cjs.map +0 -1
  114. package/dist/queue/index.d.cts +0 -1265
  115. package/dist/queue-redis/index.cjs +0 -873
  116. package/dist/queue-redis/index.cjs.map +0 -1
  117. package/dist/queue-redis/index.d.cts +0 -82
  118. package/dist/redis/index.cjs +0 -153
  119. package/dist/redis/index.cjs.map +0 -1
  120. package/dist/redis/index.d.cts +0 -82
  121. package/dist/retry/index.cjs +0 -146
  122. package/dist/retry/index.cjs.map +0 -1
  123. package/dist/retry/index.d.cts +0 -172
  124. package/dist/router/index.cjs +0 -111
  125. package/dist/router/index.cjs.map +0 -1
  126. package/dist/router/index.d.cts +0 -46
  127. package/dist/scheduler/index.cjs +0 -576
  128. package/dist/scheduler/index.cjs.map +0 -1
  129. package/dist/scheduler/index.d.cts +0 -145
  130. package/dist/security/index.cjs +0 -2402
  131. package/dist/security/index.cjs.map +0 -1
  132. package/dist/security/index.d.cts +0 -598
  133. package/dist/server/index.cjs +0 -1680
  134. package/dist/server/index.cjs.map +0 -1
  135. package/dist/server/index.d.cts +0 -810
  136. package/dist/server-auth/index.cjs +0 -3146
  137. package/dist/server-auth/index.cjs.map +0 -1
  138. package/dist/server-auth/index.d.cts +0 -1164
  139. package/dist/server-cache/index.cjs +0 -252
  140. package/dist/server-cache/index.cjs.map +0 -1
  141. package/dist/server-cache/index.d.cts +0 -164
  142. package/dist/server-compress/index.cjs +0 -141
  143. package/dist/server-compress/index.cjs.map +0 -1
  144. package/dist/server-compress/index.d.cts +0 -38
  145. package/dist/server-cookies/index.cjs +0 -234
  146. package/dist/server-cookies/index.cjs.map +0 -1
  147. package/dist/server-cookies/index.d.cts +0 -144
  148. package/dist/server-cors/index.cjs +0 -201
  149. package/dist/server-cors/index.cjs.map +0 -1
  150. package/dist/server-cors/index.d.cts +0 -140
  151. package/dist/server-health/index.cjs +0 -62
  152. package/dist/server-health/index.cjs.map +0 -1
  153. package/dist/server-health/index.d.cts +0 -58
  154. package/dist/server-helmet/index.cjs +0 -131
  155. package/dist/server-helmet/index.cjs.map +0 -1
  156. package/dist/server-helmet/index.d.cts +0 -97
  157. package/dist/server-links/index.cjs +0 -992
  158. package/dist/server-links/index.cjs.map +0 -1
  159. package/dist/server-links/index.d.cts +0 -513
  160. package/dist/server-metrics/index.cjs +0 -4535
  161. package/dist/server-metrics/index.cjs.map +0 -1
  162. package/dist/server-metrics/index.d.cts +0 -35
  163. package/dist/server-multipart/index.cjs +0 -237
  164. package/dist/server-multipart/index.cjs.map +0 -1
  165. package/dist/server-multipart/index.d.cts +0 -50
  166. package/dist/server-proxy/index.cjs +0 -186
  167. package/dist/server-proxy/index.cjs.map +0 -1
  168. package/dist/server-proxy/index.d.cts +0 -234
  169. package/dist/server-rate-limit/index.cjs +0 -241
  170. package/dist/server-rate-limit/index.cjs.map +0 -1
  171. package/dist/server-rate-limit/index.d.cts +0 -183
  172. package/dist/server-security/index.cjs +0 -316
  173. package/dist/server-security/index.cjs.map +0 -1
  174. package/dist/server-security/index.d.cts +0 -173
  175. package/dist/server-static/index.cjs +0 -170
  176. package/dist/server-static/index.cjs.map +0 -1
  177. package/dist/server-static/index.d.cts +0 -121
  178. package/dist/server-swagger/index.cjs +0 -1021
  179. package/dist/server-swagger/index.cjs.map +0 -1
  180. package/dist/server-swagger/index.d.cts +0 -382
  181. package/dist/sms/index.cjs +0 -221
  182. package/dist/sms/index.cjs.map +0 -1
  183. package/dist/sms/index.d.cts +0 -130
  184. package/dist/thread/index.cjs +0 -350
  185. package/dist/thread/index.cjs.map +0 -1
  186. package/dist/thread/index.d.cts +0 -260
  187. package/dist/topic/index.cjs +0 -282
  188. package/dist/topic/index.cjs.map +0 -1
  189. package/dist/topic/index.d.cts +0 -523
  190. package/dist/topic-redis/index.cjs +0 -71
  191. package/dist/topic-redis/index.cjs.map +0 -1
  192. package/dist/topic-redis/index.d.cts +0 -42
  193. package/dist/vite/index.cjs +0 -1077
  194. package/dist/vite/index.cjs.map +0 -1
  195. package/dist/vite/index.d.cts +0 -542
  196. package/dist/websocket/index.cjs +0 -1117
  197. package/dist/websocket/index.cjs.map +0 -1
  198. package/dist/websocket/index.d.cts +0 -861
@@ -1,523 +0,0 @@
1
- import * as alepha1 from "alepha";
2
- import { Alepha, Descriptor, KIND, Service, Static, TSchema } from "alepha";
3
- import * as alepha_logger0 from "alepha/logger";
4
- import { DateTimeProvider, DurationLike } from "alepha/datetime";
5
-
6
- //#region src/topic/providers/TopicProvider.d.ts
7
- /**
8
- * Base class for topic providers.
9
- */
10
- declare abstract class TopicProvider {
11
- protected readonly alepha: Alepha;
12
- /**
13
- * Publish a message to a topic.
14
- *
15
- * @param topic - The topic to publish to.
16
- * @param message - The message to publish.
17
- */
18
- abstract publish(topic: string, message: string): Promise<void>;
19
- /**
20
- * Subscribe to a topic.
21
- *
22
- * @param topic - The topic to subscribe to.
23
- * @param callback - The callback to call when a message is received.
24
- */
25
- abstract subscribe(topic: string, callback: SubscribeCallback): Promise<UnSubscribeFn>;
26
- /**
27
- * Unsubscribe from a topic.
28
- *
29
- * @param topic - The topic to unsubscribe from.
30
- */
31
- abstract unsubscribe(topic: string): Promise<void>;
32
- /**
33
- * Returns the list of $subscribers for this provider.
34
- */
35
- protected subscribers(): Array<() => Promise<unknown>>;
36
- }
37
- type SubscribeCallback = (message: string) => Promise<void> | void;
38
- type UnSubscribeFn = () => Promise<void>;
39
- //#endregion
40
- //#region src/topic/descriptors/$topic.d.ts
41
- /**
42
- * Creates a topic descriptor for publish/subscribe messaging and event-driven architecture.
43
- *
44
- * Enables decoupled communication through a pub/sub pattern where publishers send messages
45
- * and multiple subscribers receive them. Supports type-safe messages, real-time delivery,
46
- * event filtering, and pluggable backends (memory, Redis, custom providers).
47
- *
48
- * **Use Cases**: User notifications, real-time chat, event broadcasting, microservice communication
49
- *
50
- * @example
51
- * ```ts
52
- * class NotificationService {
53
- * userActivity = $topic({
54
- * name: "user-activity",
55
- * schema: {
56
- * payload: t.object({
57
- * userId: t.text(),
58
- * action: t.enum(["login", "logout", "purchase"]),
59
- * timestamp: t.number()
60
- * })
61
- * },
62
- * handler: async (message) => {
63
- * console.log(`User ${message.payload.userId}: ${message.payload.action}`);
64
- * }
65
- * });
66
- *
67
- * async trackLogin(userId: string) {
68
- * await this.userActivity.publish({ userId, action: "login", timestamp: Date.now() });
69
- * }
70
- *
71
- * async subscribeToEvents() {
72
- * await this.userActivity.subscribe(async (message) => {
73
- * // Additional subscriber logic
74
- * });
75
- * }
76
- * }
77
- * ```
78
- */
79
- declare const $topic: {
80
- <T extends TopicMessageSchema>(options: TopicDescriptorOptions<T>): TopicDescriptor<T>;
81
- [KIND]: typeof TopicDescriptor;
82
- };
83
- interface TopicDescriptorOptions<T extends TopicMessageSchema> {
84
- /**
85
- * Unique name identifier for the topic.
86
- *
87
- * This name is used for:
88
- * - Topic identification across the pub/sub system
89
- * - Message routing between publishers and subscribers
90
- * - Logging and debugging topic-related operations
91
- * - Provider-specific topic management (channels, keys, etc.)
92
- *
93
- * If not provided, defaults to the property key where the topic is declared.
94
- *
95
- * **Naming Conventions**:
96
- * - Use descriptive, hierarchical names: "user.activity", "order.events"
97
- * - Avoid spaces and special characters
98
- * - Consider using dot notation for categorization
99
- * - Keep names concise but meaningful
100
- *
101
- * @example "user-activity"
102
- * @example "chat.messages"
103
- * @example "system.health.checks"
104
- * @example "payment.webhooks"
105
- */
106
- name?: string;
107
- /**
108
- * Human-readable description of the topic's purpose and usage.
109
- *
110
- * Used for:
111
- * - Documentation generation and API references
112
- * - Developer onboarding and understanding
113
- * - Monitoring dashboards and admin interfaces
114
- * - Team communication about system architecture
115
- *
116
- * **Description Best Practices**:
117
- * - Explain what events/messages this topic handles
118
- * - Mention key use cases and subscribers
119
- * - Include any important timing or ordering guarantees
120
- * - Note any special processing requirements
121
- *
122
- * @example "Real-time user activity events for analytics and notifications"
123
- * @example "Order lifecycle events from creation to delivery"
124
- * @example "Chat messages broadcast to all room participants"
125
- * @example "System health checks and service status updates"
126
- */
127
- description?: string;
128
- /**
129
- * Topic provider configuration for message storage and delivery.
130
- *
131
- * Options:
132
- * - **"memory"**: In-memory provider (default for development, lost on restart)
133
- * - **Service<TopicProvider>**: Custom provider class (e.g., RedisTopicProvider)
134
- * - **undefined**: Uses the default topic provider from dependency injection
135
- *
136
- * **Provider Selection Guidelines**:
137
- * - **Development**: Use "memory" for fast, simple testing without external dependencies
138
- * - **Production**: Use Redis or message brokers for persistence and scalability
139
- * - **Distributed systems**: Use Redis/RabbitMQ for cross-service communication
140
- * - **High-throughput**: Use specialized providers with connection pooling
141
- * - **Real-time**: Ensure provider supports low-latency message delivery
142
- *
143
- * **Provider Capabilities**:
144
- * - Message persistence and durability
145
- * - Subscriber management and connection handling
146
- * - Message ordering and delivery guarantees
147
- * - Horizontal scaling and load distribution
148
- *
149
- * @default Uses injected TopicProvider
150
- * @example "memory"
151
- * @example RedisTopicProvider
152
- * @example RabbitMQTopicProvider
153
- */
154
- provider?: "memory" | Service<TopicProvider>;
155
- /**
156
- * TypeBox schema defining the structure of messages published to this topic.
157
- *
158
- * The schema must include:
159
- * - **payload**: Required schema for the main message data
160
- * - **headers**: Optional schema for message metadata
161
- *
162
- * This schema:
163
- * - Validates all messages published to the topic
164
- * - Provides full TypeScript type inference for subscribers
165
- * - Ensures type safety between publishers and subscribers
166
- * - Enables automatic serialization/deserialization
167
- *
168
- * **Schema Design Best Practices**:
169
- * - Keep payload schemas focused and cohesive
170
- * - Use optional fields for data that might not always be present
171
- * - Include timestamp fields for event ordering
172
- * - Consider versioning for schema evolution
173
- * - Use union types for different event types in the same topic
174
- *
175
- * @example
176
- * ```ts
177
- * {
178
- * payload: t.object({
179
- * eventId: t.text(),
180
- * eventType: t.enum(["created", "updated"]),
181
- * data: t.record(t.text(), t.any()),
182
- * timestamp: t.number(),
183
- * userId: t.optional(t.text())
184
- * }),
185
- * headers: t.optional(t.object({
186
- * source: t.text(),
187
- * correlationId: t.text()
188
- * }))
189
- * }
190
- * ```
191
- */
192
- schema: T;
193
- /**
194
- * Default subscriber handler function that processes messages published to this topic.
195
- *
196
- * This handler:
197
- * - Automatically subscribes when the topic is initialized
198
- * - Receives all messages published to the topic
199
- * - Runs for every message without additional subscription setup
200
- * - Can be supplemented with additional subscribers via `subscribe()` method
201
- * - Should handle errors gracefully to avoid breaking other subscribers
202
- *
203
- * **Handler Design Guidelines**:
204
- * - Keep handlers focused on a single responsibility
205
- * - Use proper error handling and logging
206
- * - Consider performance impact for high-frequency topics
207
- * - Make handlers idempotent when possible
208
- * - Validate business rules within the handler logic
209
- * - Log important processing steps for debugging
210
- *
211
- * **Error Handling Strategy**:
212
- * - Log errors but don't re-throw to avoid affecting other subscribers
213
- * - Use try-catch blocks for external service calls
214
- * - Consider implementing circuit breakers for resilience
215
- * - Monitor error rates and patterns for system health
216
- *
217
- * @param message - The topic message with validated payload and headers
218
- * @param message.payload - The typed message data based on the schema
219
- * @returns Promise that resolves when processing is complete
220
- *
221
- * @example
222
- * ```ts
223
- * handler: async (message) => {
224
- * const { eventType, data, timestamp } = message.payload;
225
- *
226
- * try {
227
- * // Log message receipt
228
- * this.logger.info(`Processing ${eventType} event`, { timestamp, data });
229
- *
230
- * // Process based on event type
231
- * switch (eventType) {
232
- * case "created":
233
- * await this.handleCreation(data);
234
- * break;
235
- * case "updated":
236
- * await this.handleUpdate(data);
237
- * break;
238
- * default:
239
- * this.logger.warn(`Unknown event type: ${eventType}`);
240
- * }
241
- *
242
- * this.logger.info(`Successfully processed ${eventType} event`);
243
- *
244
- * } catch (error) {
245
- * // Log error but don't re-throw to avoid affecting other subscribers
246
- * this.logger.error(`Failed to process ${eventType} event`, {
247
- * error: error.message,
248
- * eventType,
249
- * timestamp,
250
- * data
251
- * });
252
- * }
253
- * }
254
- * ```
255
- */
256
- handler?: TopicHandler<T>;
257
- }
258
- declare class TopicDescriptor<T extends TopicMessageSchema> extends Descriptor<TopicDescriptorOptions<T>> {
259
- protected readonly log: alepha_logger0.Logger;
260
- protected readonly dateTimeProvider: DateTimeProvider;
261
- readonly provider: TopicProvider;
262
- get name(): string;
263
- publish(payload: TopicMessage<T>["payload"]): Promise<void>;
264
- subscribe(handler: TopicHandler<T>): Promise<UnSubscribeFn>;
265
- wait(options?: TopicWaitOptions<T>): Promise<TopicMessage<T>>;
266
- protected $provider(): TopicProvider;
267
- protected parseMessage(message: string): TopicMessage<T>;
268
- }
269
- interface TopicMessage<T extends TopicMessageSchema> {
270
- payload: Static<T["payload"]>;
271
- }
272
- interface TopicWaitOptions<T extends TopicMessageSchema> {
273
- timeout?: DurationLike;
274
- filter?: (message: {
275
- payload: Static<T["payload"]>;
276
- }) => boolean;
277
- }
278
- interface TopicMessageSchema {
279
- payload: TSchema;
280
- }
281
- type TopicHandler<T extends TopicMessageSchema = TopicMessageSchema> = (message: TopicMessage<T>) => unknown;
282
- //#endregion
283
- //#region src/topic/descriptors/$subscriber.d.ts
284
- /**
285
- * Creates a subscriber descriptor to listen for messages from a specific topic.
286
- *
287
- * Provides a dedicated message subscriber that connects to a topic and processes messages
288
- * with custom handler logic, enabling scalable pub/sub architectures where multiple
289
- * subscribers can react to the same events independently.
290
- *
291
- * **Key Features**
292
- * - Seamless integration with any $topic descriptor
293
- * - Full type safety inherited from topic schema
294
- * - Real-time message delivery when events are published
295
- * - Error isolation between subscribers
296
- * - Support for multiple independent subscribers per topic
297
- *
298
- * **Common Use Cases**
299
- * - Notification services and audit logging
300
- * - Analytics and metrics collection
301
- * - Data synchronization and real-time UI updates
302
- *
303
- * @example
304
- * ```ts
305
- * class UserActivityService {
306
- * userEvents = $topic({
307
- * name: "user-activity",
308
- * schema: {
309
- * payload: t.object({
310
- * userId: t.text(),
311
- * action: t.enum(["login", "logout", "purchase"]),
312
- * timestamp: t.number()
313
- * })
314
- * }
315
- * });
316
- *
317
- * activityLogger = $subscriber({
318
- * topic: this.userEvents,
319
- * handler: async (message) => {
320
- * const { userId, action, timestamp } = message.payload;
321
- * await this.auditLogger.log({
322
- * userId,
323
- * action,
324
- * timestamp
325
- * });
326
- * }
327
- * });
328
- *
329
- * async trackUserLogin(userId: string) {
330
- * await this.userEvents.publish({
331
- * userId,
332
- * action: "login",
333
- * timestamp: Date.now()
334
- * });
335
- * }
336
- * }
337
- * ```
338
- */
339
- declare const $subscriber: {
340
- <T extends TopicMessageSchema>(options: SubscriberDescriptorOptions<T>): SubscriberDescriptor<T>;
341
- [KIND]: typeof SubscriberDescriptor;
342
- };
343
- interface SubscriberDescriptorOptions<T extends TopicMessageSchema> {
344
- /**
345
- * The topic descriptor that this subscriber will listen to for messages.
346
- *
347
- * This establishes the connection between the subscriber and its source topic:
348
- * - The subscriber inherits the topic's message schema for type safety
349
- * - Messages published to the topic will be automatically delivered to this subscriber
350
- * - Multiple subscribers can listen to the same topic independently
351
- * - The subscriber will use the topic's provider and configuration settings
352
- *
353
- * **Topic Integration Benefits**:
354
- * - Type safety: Subscriber handler gets fully typed message payloads
355
- * - Schema validation: Messages are validated before reaching the subscriber
356
- * - Real-time delivery: Messages are delivered immediately upon publication
357
- * - Error isolation: Subscriber errors don't affect the topic or other subscribers
358
- * - Monitoring: Topic metrics include subscriber processing statistics
359
- *
360
- * @example
361
- * ```ts
362
- * // First, define a topic
363
- * userEvents = $topic({
364
- * name: "user-activity",
365
- * schema: {
366
- * payload: t.object({ userId: t.text(), action: t.text() })
367
- * }
368
- * });
369
- *
370
- * // Then, create a subscriber for that topic
371
- * activitySubscriber = $subscriber({
372
- * topic: this.userEvents, // Reference the topic descriptor
373
- * handler: async (message) => { } // Process messages here
374
- * });
375
- * ```
376
- */
377
- topic: TopicDescriptor<T>;
378
- /**
379
- * Message handler function that processes individual messages from the topic.
380
- *
381
- * This function:
382
- * - Receives fully typed and validated message payloads from the connected topic
383
- * - Executes immediately when messages are published to the topic
384
- * - Should implement the core business logic for reacting to these events
385
- * - Runs independently of other subscribers to the same topic
386
- * - Should handle errors gracefully to avoid affecting other subscribers
387
- * - Has access to the full Alepha dependency injection container
388
- *
389
- * **Handler Design Guidelines**:
390
- * - Keep handlers focused on a single responsibility
391
- * - Use proper error handling and logging
392
- * - Consider performance impact for high-frequency topics
393
- * - Make handlers idempotent when possible for reliability
394
- * - Validate business rules within the handler logic
395
- * - Log important processing steps for debugging and monitoring
396
- *
397
- * **Error Handling Strategy**:
398
- * - Log errors but don't re-throw to avoid affecting other subscribers
399
- * - Use try-catch blocks for external service calls
400
- * - Implement circuit breakers for resilience with external systems
401
- * - Monitor error rates and patterns for system health
402
- * - Consider implementing retry logic for temporary failures
403
- *
404
- * **Performance Considerations**:
405
- * - Keep handler execution time minimal for high-throughput topics
406
- * - Use background queues for heavy processing triggered by events
407
- * - Implement batching for efficiency when processing many similar events
408
- * - Consider async processing patterns for non-critical operations
409
- *
410
- * @param message - The topic message with validated payload and optional headers
411
- * @param message.payload - The typed message data based on the topic's schema
412
- * @returns Promise that resolves when processing is complete
413
- *
414
- * @example
415
- * ```ts
416
- * handler: async (message) => {
417
- * const { userId, eventType, timestamp } = message.payload;
418
- *
419
- * try {
420
- * // Log event receipt
421
- * this.logger.info(`Processing ${eventType} event for user ${userId}`, {
422
- * timestamp,
423
- * userId,
424
- * eventType
425
- * });
426
- *
427
- * // Perform event-specific processing
428
- * switch (eventType) {
429
- * case 'user.login':
430
- * await this.updateLastLogin(userId, timestamp);
431
- * await this.sendWelcomeNotification(userId);
432
- * break;
433
- * case 'user.logout':
434
- * await this.updateSessionDuration(userId, timestamp);
435
- * break;
436
- * case 'user.purchase':
437
- * await this.updateRewardsPoints(userId, message.payload.purchaseAmount);
438
- * await this.triggerRecommendations(userId);
439
- * break;
440
- * default:
441
- * this.logger.warn(`Unknown event type: ${eventType}`);
442
- * }
443
- *
444
- * // Update analytics
445
- * await this.analytics.track(eventType, {
446
- * userId,
447
- * timestamp,
448
- * source: 'topic-subscriber'
449
- * });
450
- *
451
- * this.logger.info(`Successfully processed ${eventType} for user ${userId}`);
452
- *
453
- * } catch (error) {
454
- * // Log error but don't re-throw to avoid affecting other subscribers
455
- * this.logger.error(`Failed to process ${eventType} for user ${userId}`, {
456
- * error: error.message,
457
- * stack: error.stack,
458
- * userId,
459
- * eventType,
460
- * timestamp
461
- * });
462
- *
463
- * // Optionally send to error tracking service
464
- * await this.errorTracker.captureException(error, {
465
- * context: { userId, eventType, timestamp },
466
- * tags: { component: 'topic-subscriber' }
467
- * });
468
- * }
469
- * }
470
- * ```
471
- */
472
- handler: TopicHandler<T>;
473
- }
474
- declare class SubscriberDescriptor<T extends TopicMessageSchema> extends Descriptor<SubscriberDescriptorOptions<T>> {}
475
- //#endregion
476
- //#region src/topic/errors/TopicTimeoutError.d.ts
477
- declare class TopicTimeoutError extends Error {
478
- readonly topic: string;
479
- readonly timeout: number;
480
- constructor(topic: string, timeout: number);
481
- }
482
- //#endregion
483
- //#region src/topic/providers/MemoryTopicProvider.d.ts
484
- declare class MemoryTopicProvider extends TopicProvider {
485
- protected readonly log: alepha_logger0.Logger;
486
- protected readonly subscriptions: Record<string, SubscribeCallback[]>;
487
- protected readonly start: alepha1.HookDescriptor<"start">;
488
- /**
489
- * Publish a message to a topic.
490
- *
491
- * @param topic
492
- * @param message
493
- */
494
- publish(topic: string, message: string): Promise<void>;
495
- /**
496
- * Subscribe to a topic.
497
- *
498
- * @param topic - The topic to subscribe to.
499
- * @param callback
500
- */
501
- subscribe(topic: string, callback: SubscribeCallback): Promise<UnSubscribeFn>;
502
- /**
503
- * Unsubscribe from a topic.
504
- *
505
- * @param topic - The topic to unsubscribe from.
506
- */
507
- unsubscribe(topic: string): Promise<void>;
508
- }
509
- //#endregion
510
- //#region src/topic/index.d.ts
511
- /**
512
- * Generic interface for pub/sub messaging.
513
- * Gives you the ability to create topics and subscribers.
514
- * This module provides only a memory implementation of the topic provider.
515
- *
516
- * @see {@link $topic}
517
- * @see {@link $subscriber}
518
- * @module alepha.topic
519
- */
520
- declare const AlephaTopic: alepha1.Service<alepha1.Module>;
521
- //#endregion
522
- export { $subscriber, $topic, AlephaTopic, MemoryTopicProvider, SubscribeCallback, SubscriberDescriptor, SubscriberDescriptorOptions, TopicDescriptor, TopicDescriptorOptions, TopicHandler, TopicMessage, TopicMessageSchema, TopicProvider, TopicTimeoutError, TopicWaitOptions, UnSubscribeFn };
523
- //# sourceMappingURL=index.d.cts.map
@@ -1,71 +0,0 @@
1
- let alepha = require("alepha");
2
- let alepha_topic = require("alepha/topic");
3
- let alepha_logger = require("alepha/logger");
4
- let alepha_redis = require("alepha/redis");
5
-
6
- //#region src/topic-redis/providers/RedisTopicProvider.ts
7
- const envSchema = alepha.t.object({ REDIS_TOPIC_PREFIX: alepha.t.text({ default: "topic" }) });
8
- var RedisTopicProvider = class extends alepha_topic.TopicProvider {
9
- env = (0, alepha.$env)(envSchema);
10
- alepha = (0, alepha.$inject)(alepha.Alepha);
11
- redisProvider = (0, alepha.$inject)(alepha_redis.RedisProvider);
12
- redisSubscriberProvider = (0, alepha.$inject)(alepha_redis.RedisSubscriberProvider);
13
- log = (0, alepha_logger.$logger)();
14
- start = (0, alepha.$hook)({
15
- on: "start",
16
- handler: async () => {
17
- const subscribers = this.subscribers();
18
- if (subscribers.length) {
19
- await Promise.all(subscribers.map((fn) => fn()));
20
- for (const subscriber of subscribers) this.log.debug(`Subscribed to topic '${subscriber.name}'`);
21
- }
22
- }
23
- });
24
- prefix(queue) {
25
- return `${this.env.REDIS_TOPIC_PREFIX}:${queue}`;
26
- }
27
- /**
28
- * Publish a message to a topic.
29
- */
30
- async publish(topic, message) {
31
- await this.redisProvider.publisher.publish(this.prefix(topic), message);
32
- }
33
- /**
34
- * Subscribe to a topic.
35
- */
36
- async subscribe(name, callback) {
37
- const topic = this.prefix(name);
38
- await this.redisSubscriberProvider.subscriber.subscribe(topic, callback);
39
- return () => this.unsubscribe(name, callback);
40
- }
41
- /**
42
- * Unsubscribe from a topic.
43
- */
44
- async unsubscribe(name, callback) {
45
- const topic = this.prefix(name);
46
- await this.redisSubscriberProvider.subscriber.unsubscribe(topic, callback);
47
- }
48
- };
49
-
50
- //#endregion
51
- //#region src/topic-redis/index.ts
52
- /**
53
- * Plugin for Alepha Topic that provides Redis pub/sub capabilities.
54
- *
55
- * @see {@link RedisTopicProvider}
56
- * @module alepha.topic.redis
57
- */
58
- const AlephaTopicRedis = (0, alepha.$module)({
59
- name: "alepha.topic.redis",
60
- services: [RedisTopicProvider],
61
- register: (alepha$1) => alepha$1.with({
62
- optional: true,
63
- provide: alepha_topic.TopicProvider,
64
- use: RedisTopicProvider
65
- }).with(alepha_topic.AlephaTopic)
66
- });
67
-
68
- //#endregion
69
- exports.AlephaTopicRedis = AlephaTopicRedis;
70
- exports.RedisTopicProvider = RedisTopicProvider;
71
- //# sourceMappingURL=index.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.cjs","names":["t","TopicProvider","Alepha","RedisProvider","RedisSubscriberProvider","alepha","TopicProvider","AlephaTopic"],"sources":["../../src/topic-redis/providers/RedisTopicProvider.ts","../../src/topic-redis/index.ts"],"sourcesContent":["import { $env, $hook, $inject, Alepha, t } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { RedisProvider, RedisSubscriberProvider } from \"alepha/redis\";\nimport {\n type SubscribeCallback,\n TopicProvider,\n type UnSubscribeFn,\n} from \"alepha/topic\";\n\nconst envSchema = t.object({\n REDIS_TOPIC_PREFIX: t.text({\n default: \"topic\",\n }),\n});\n\nexport class RedisTopicProvider extends TopicProvider {\n protected readonly env = $env(envSchema);\n protected readonly alepha = $inject(Alepha);\n protected readonly redisProvider = $inject(RedisProvider);\n protected readonly redisSubscriberProvider = $inject(RedisSubscriberProvider);\n\n protected readonly log = $logger();\n\n protected readonly start = $hook({\n on: \"start\",\n handler: async () => {\n const subscribers = this.subscribers();\n if (subscribers.length) {\n await Promise.all(subscribers.map((fn) => fn()));\n for (const subscriber of subscribers) {\n this.log.debug(`Subscribed to topic '${subscriber.name}'`);\n }\n }\n },\n });\n\n public prefix(queue: string): string {\n return `${this.env.REDIS_TOPIC_PREFIX}:${queue}`;\n }\n\n /**\n * Publish a message to a topic.\n */\n public async publish(topic: string, message: string): Promise<void> {\n await this.redisProvider.publisher.publish(this.prefix(topic), message);\n }\n\n /**\n * Subscribe to a topic.\n */\n public async subscribe(\n name: string,\n callback: SubscribeCallback,\n ): Promise<UnSubscribeFn> {\n const topic = this.prefix(name);\n await this.redisSubscriberProvider.subscriber.subscribe(topic, callback);\n\n return () => this.unsubscribe(name, callback);\n }\n\n /**\n * Unsubscribe from a topic.\n */\n public async unsubscribe(\n name: string,\n callback?: SubscribeCallback,\n ): Promise<void> {\n const topic = this.prefix(name);\n\n await this.redisSubscriberProvider.subscriber.unsubscribe(topic, callback);\n }\n}\n","import { $module, type Alepha } from \"alepha\";\nimport { AlephaTopic, TopicProvider } from \"alepha/topic\";\nimport { RedisTopicProvider } from \"./providers/RedisTopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/RedisTopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Topic that provides Redis pub/sub capabilities.\n *\n * @see {@link RedisTopicProvider}\n * @module alepha.topic.redis\n */\nexport const AlephaTopicRedis = $module({\n name: \"alepha.topic.redis\",\n services: [RedisTopicProvider],\n register: (alepha: Alepha): Alepha =>\n alepha\n .with({\n optional: true,\n provide: TopicProvider,\n use: RedisTopicProvider,\n })\n .with(AlephaTopic),\n});\n"],"mappings":";;;;;;AASA,MAAM,YAAYA,SAAE,OAAO,EACzB,oBAAoBA,SAAE,KAAK,EACzB,SAAS,SACV,CAAC,EACH,CAAC;AAEF,IAAa,qBAAb,cAAwCC,2BAAc;CACpD,AAAmB,uBAAW,UAAU;CACxC,AAAmB,6BAAiBC,cAAO;CAC3C,AAAmB,oCAAwBC,2BAAc;CACzD,AAAmB,8CAAkCC,qCAAwB;CAE7E,AAAmB,kCAAe;CAElC,AAAmB,0BAAc;EAC/B,IAAI;EACJ,SAAS,YAAY;GACnB,MAAM,cAAc,KAAK,aAAa;AACtC,OAAI,YAAY,QAAQ;AACtB,UAAM,QAAQ,IAAI,YAAY,KAAK,OAAO,IAAI,CAAC,CAAC;AAChD,SAAK,MAAM,cAAc,YACvB,MAAK,IAAI,MAAM,wBAAwB,WAAW,KAAK,GAAG;;;EAIjE,CAAC;CAEF,AAAO,OAAO,OAAuB;AACnC,SAAO,GAAG,KAAK,IAAI,mBAAmB,GAAG;;;;;CAM3C,MAAa,QAAQ,OAAe,SAAgC;AAClE,QAAM,KAAK,cAAc,UAAU,QAAQ,KAAK,OAAO,MAAM,EAAE,QAAQ;;;;;CAMzE,MAAa,UACX,MACA,UACwB;EACxB,MAAM,QAAQ,KAAK,OAAO,KAAK;AAC/B,QAAM,KAAK,wBAAwB,WAAW,UAAU,OAAO,SAAS;AAExE,eAAa,KAAK,YAAY,MAAM,SAAS;;;;;CAM/C,MAAa,YACX,MACA,UACe;EACf,MAAM,QAAQ,KAAK,OAAO,KAAK;AAE/B,QAAM,KAAK,wBAAwB,WAAW,YAAY,OAAO,SAAS;;;;;;;;;;;;ACrD9E,MAAa,uCAA2B;CACtC,MAAM;CACN,UAAU,CAAC,mBAAmB;CAC9B,WAAW,aACTC,SACG,KAAK;EACJ,UAAU;EACV,SAASC;EACT,KAAK;EACN,CAAC,CACD,KAAKC,yBAAY;CACvB,CAAC"}
@@ -1,42 +0,0 @@
1
- import * as alepha1 from "alepha";
2
- import { Alepha } from "alepha";
3
- import * as alepha_logger0 from "alepha/logger";
4
- import { RedisProvider, RedisSubscriberProvider } from "alepha/redis";
5
- import { SubscribeCallback, TopicProvider, UnSubscribeFn } from "alepha/topic";
6
-
7
- //#region src/topic-redis/providers/RedisTopicProvider.d.ts
8
- declare class RedisTopicProvider extends TopicProvider {
9
- protected readonly env: {
10
- REDIS_TOPIC_PREFIX: string;
11
- };
12
- protected readonly alepha: Alepha;
13
- protected readonly redisProvider: RedisProvider;
14
- protected readonly redisSubscriberProvider: RedisSubscriberProvider;
15
- protected readonly log: alepha_logger0.Logger;
16
- protected readonly start: alepha1.HookDescriptor<"start">;
17
- prefix(queue: string): string;
18
- /**
19
- * Publish a message to a topic.
20
- */
21
- publish(topic: string, message: string): Promise<void>;
22
- /**
23
- * Subscribe to a topic.
24
- */
25
- subscribe(name: string, callback: SubscribeCallback): Promise<UnSubscribeFn>;
26
- /**
27
- * Unsubscribe from a topic.
28
- */
29
- unsubscribe(name: string, callback?: SubscribeCallback): Promise<void>;
30
- }
31
- //#endregion
32
- //#region src/topic-redis/index.d.ts
33
- /**
34
- * Plugin for Alepha Topic that provides Redis pub/sub capabilities.
35
- *
36
- * @see {@link RedisTopicProvider}
37
- * @module alepha.topic.redis
38
- */
39
- declare const AlephaTopicRedis: alepha1.Service<alepha1.Module>;
40
- //#endregion
41
- export { AlephaTopicRedis, RedisTopicProvider };
42
- //# sourceMappingURL=index.d.cts.map