alepha 0.13.0 → 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 (195) hide show
  1. package/dist/api-jobs/index.d.ts +26 -26
  2. package/dist/api-users/index.d.ts +1 -1
  3. package/dist/cli/{dist-Sz2EXvQX.cjs → dist-Dl9Vl7Ur.js} +17 -13
  4. package/dist/cli/{dist-BBPjuQ56.js.map → dist-Dl9Vl7Ur.js.map} +1 -1
  5. package/dist/cli/index.d.ts +3 -11
  6. package/dist/cli/index.js +106 -74
  7. package/dist/cli/index.js.map +1 -1
  8. package/dist/email/index.js +71 -73
  9. package/dist/email/index.js.map +1 -1
  10. package/dist/orm/index.d.ts +1 -1
  11. package/dist/orm/index.js.map +1 -1
  12. package/dist/queue/index.d.ts +4 -4
  13. package/dist/retry/index.d.ts +1 -1
  14. package/dist/retry/index.js +2 -2
  15. package/dist/retry/index.js.map +1 -1
  16. package/dist/scheduler/index.d.ts +6 -6
  17. package/dist/security/index.d.ts +28 -28
  18. package/dist/server/index.js +1 -1
  19. package/dist/server/index.js.map +1 -1
  20. package/dist/server-health/index.d.ts +17 -17
  21. package/dist/server-metrics/index.js +170 -174
  22. package/dist/server-metrics/index.js.map +1 -1
  23. package/dist/server-security/index.d.ts +9 -9
  24. package/dist/vite/index.js +4 -5
  25. package/dist/vite/index.js.map +1 -1
  26. package/dist/websocket/index.d.ts +7 -7
  27. package/package.json +52 -103
  28. package/src/cli/apps/AlephaPackageBuilderCli.ts +7 -2
  29. package/src/cli/assets/appRouterTs.ts +9 -0
  30. package/src/cli/assets/indexHtml.ts +2 -1
  31. package/src/cli/assets/mainBrowserTs.ts +10 -0
  32. package/src/cli/commands/CoreCommands.ts +6 -5
  33. package/src/cli/commands/DrizzleCommands.ts +65 -57
  34. package/src/cli/commands/VerifyCommands.ts +1 -1
  35. package/src/cli/services/ProjectUtils.ts +44 -38
  36. package/src/orm/providers/DrizzleKitProvider.ts +1 -1
  37. package/src/retry/descriptors/$retry.ts +5 -3
  38. package/src/server/providers/NodeHttpServerProvider.ts +1 -1
  39. package/src/vite/helpers/boot.ts +3 -3
  40. package/dist/api-files/index.cjs +0 -1293
  41. package/dist/api-files/index.cjs.map +0 -1
  42. package/dist/api-files/index.d.cts +0 -829
  43. package/dist/api-jobs/index.cjs +0 -274
  44. package/dist/api-jobs/index.cjs.map +0 -1
  45. package/dist/api-jobs/index.d.cts +0 -654
  46. package/dist/api-notifications/index.cjs +0 -380
  47. package/dist/api-notifications/index.cjs.map +0 -1
  48. package/dist/api-notifications/index.d.cts +0 -289
  49. package/dist/api-parameters/index.cjs +0 -66
  50. package/dist/api-parameters/index.cjs.map +0 -1
  51. package/dist/api-parameters/index.d.cts +0 -84
  52. package/dist/api-users/index.cjs +0 -6009
  53. package/dist/api-users/index.cjs.map +0 -1
  54. package/dist/api-users/index.d.cts +0 -4740
  55. package/dist/api-verifications/index.cjs +0 -407
  56. package/dist/api-verifications/index.cjs.map +0 -1
  57. package/dist/api-verifications/index.d.cts +0 -207
  58. package/dist/batch/index.cjs +0 -408
  59. package/dist/batch/index.cjs.map +0 -1
  60. package/dist/batch/index.d.cts +0 -330
  61. package/dist/bin/index.cjs +0 -17
  62. package/dist/bin/index.cjs.map +0 -1
  63. package/dist/bin/index.d.cts +0 -1
  64. package/dist/bucket/index.cjs +0 -303
  65. package/dist/bucket/index.cjs.map +0 -1
  66. package/dist/bucket/index.d.cts +0 -355
  67. package/dist/cache/index.cjs +0 -241
  68. package/dist/cache/index.cjs.map +0 -1
  69. package/dist/cache/index.d.cts +0 -202
  70. package/dist/cache-redis/index.cjs +0 -84
  71. package/dist/cache-redis/index.cjs.map +0 -1
  72. package/dist/cache-redis/index.d.cts +0 -40
  73. package/dist/cli/chunk-DSlc6foC.cjs +0 -43
  74. package/dist/cli/dist-BBPjuQ56.js +0 -2778
  75. package/dist/cli/dist-Sz2EXvQX.cjs.map +0 -1
  76. package/dist/cli/index.cjs +0 -1241
  77. package/dist/cli/index.cjs.map +0 -1
  78. package/dist/cli/index.d.cts +0 -422
  79. package/dist/command/index.cjs +0 -693
  80. package/dist/command/index.cjs.map +0 -1
  81. package/dist/command/index.d.cts +0 -340
  82. package/dist/core/index.cjs +0 -2264
  83. package/dist/core/index.cjs.map +0 -1
  84. package/dist/core/index.d.cts +0 -1927
  85. package/dist/datetime/index.cjs +0 -318
  86. package/dist/datetime/index.cjs.map +0 -1
  87. package/dist/datetime/index.d.cts +0 -145
  88. package/dist/email/index.cjs +0 -10874
  89. package/dist/email/index.cjs.map +0 -1
  90. package/dist/email/index.d.cts +0 -186
  91. package/dist/fake/index.cjs +0 -34641
  92. package/dist/fake/index.cjs.map +0 -1
  93. package/dist/fake/index.d.cts +0 -74
  94. package/dist/file/index.cjs +0 -1212
  95. package/dist/file/index.cjs.map +0 -1
  96. package/dist/file/index.d.cts +0 -698
  97. package/dist/lock/index.cjs +0 -226
  98. package/dist/lock/index.cjs.map +0 -1
  99. package/dist/lock/index.d.cts +0 -361
  100. package/dist/lock-redis/index.cjs +0 -113
  101. package/dist/lock-redis/index.cjs.map +0 -1
  102. package/dist/lock-redis/index.d.cts +0 -24
  103. package/dist/logger/index.cjs +0 -521
  104. package/dist/logger/index.cjs.map +0 -1
  105. package/dist/logger/index.d.cts +0 -281
  106. package/dist/orm/index.cjs +0 -2986
  107. package/dist/orm/index.cjs.map +0 -1
  108. package/dist/orm/index.d.cts +0 -2213
  109. package/dist/queue/index.cjs +0 -1044
  110. package/dist/queue/index.cjs.map +0 -1
  111. package/dist/queue/index.d.cts +0 -1265
  112. package/dist/queue-redis/index.cjs +0 -873
  113. package/dist/queue-redis/index.cjs.map +0 -1
  114. package/dist/queue-redis/index.d.cts +0 -82
  115. package/dist/redis/index.cjs +0 -153
  116. package/dist/redis/index.cjs.map +0 -1
  117. package/dist/redis/index.d.cts +0 -82
  118. package/dist/retry/index.cjs +0 -146
  119. package/dist/retry/index.cjs.map +0 -1
  120. package/dist/retry/index.d.cts +0 -172
  121. package/dist/router/index.cjs +0 -111
  122. package/dist/router/index.cjs.map +0 -1
  123. package/dist/router/index.d.cts +0 -46
  124. package/dist/scheduler/index.cjs +0 -576
  125. package/dist/scheduler/index.cjs.map +0 -1
  126. package/dist/scheduler/index.d.cts +0 -145
  127. package/dist/security/index.cjs +0 -2402
  128. package/dist/security/index.cjs.map +0 -1
  129. package/dist/security/index.d.cts +0 -598
  130. package/dist/server/index.cjs +0 -1680
  131. package/dist/server/index.cjs.map +0 -1
  132. package/dist/server/index.d.cts +0 -810
  133. package/dist/server-auth/index.cjs +0 -3146
  134. package/dist/server-auth/index.cjs.map +0 -1
  135. package/dist/server-auth/index.d.cts +0 -1164
  136. package/dist/server-cache/index.cjs +0 -252
  137. package/dist/server-cache/index.cjs.map +0 -1
  138. package/dist/server-cache/index.d.cts +0 -164
  139. package/dist/server-compress/index.cjs +0 -141
  140. package/dist/server-compress/index.cjs.map +0 -1
  141. package/dist/server-compress/index.d.cts +0 -38
  142. package/dist/server-cookies/index.cjs +0 -234
  143. package/dist/server-cookies/index.cjs.map +0 -1
  144. package/dist/server-cookies/index.d.cts +0 -144
  145. package/dist/server-cors/index.cjs +0 -201
  146. package/dist/server-cors/index.cjs.map +0 -1
  147. package/dist/server-cors/index.d.cts +0 -140
  148. package/dist/server-health/index.cjs +0 -62
  149. package/dist/server-health/index.cjs.map +0 -1
  150. package/dist/server-health/index.d.cts +0 -58
  151. package/dist/server-helmet/index.cjs +0 -131
  152. package/dist/server-helmet/index.cjs.map +0 -1
  153. package/dist/server-helmet/index.d.cts +0 -97
  154. package/dist/server-links/index.cjs +0 -992
  155. package/dist/server-links/index.cjs.map +0 -1
  156. package/dist/server-links/index.d.cts +0 -513
  157. package/dist/server-metrics/index.cjs +0 -4535
  158. package/dist/server-metrics/index.cjs.map +0 -1
  159. package/dist/server-metrics/index.d.cts +0 -35
  160. package/dist/server-multipart/index.cjs +0 -237
  161. package/dist/server-multipart/index.cjs.map +0 -1
  162. package/dist/server-multipart/index.d.cts +0 -50
  163. package/dist/server-proxy/index.cjs +0 -186
  164. package/dist/server-proxy/index.cjs.map +0 -1
  165. package/dist/server-proxy/index.d.cts +0 -234
  166. package/dist/server-rate-limit/index.cjs +0 -241
  167. package/dist/server-rate-limit/index.cjs.map +0 -1
  168. package/dist/server-rate-limit/index.d.cts +0 -183
  169. package/dist/server-security/index.cjs +0 -316
  170. package/dist/server-security/index.cjs.map +0 -1
  171. package/dist/server-security/index.d.cts +0 -173
  172. package/dist/server-static/index.cjs +0 -170
  173. package/dist/server-static/index.cjs.map +0 -1
  174. package/dist/server-static/index.d.cts +0 -121
  175. package/dist/server-swagger/index.cjs +0 -1021
  176. package/dist/server-swagger/index.cjs.map +0 -1
  177. package/dist/server-swagger/index.d.cts +0 -382
  178. package/dist/sms/index.cjs +0 -221
  179. package/dist/sms/index.cjs.map +0 -1
  180. package/dist/sms/index.d.cts +0 -130
  181. package/dist/thread/index.cjs +0 -350
  182. package/dist/thread/index.cjs.map +0 -1
  183. package/dist/thread/index.d.cts +0 -260
  184. package/dist/topic/index.cjs +0 -282
  185. package/dist/topic/index.cjs.map +0 -1
  186. package/dist/topic/index.d.cts +0 -523
  187. package/dist/topic-redis/index.cjs +0 -71
  188. package/dist/topic-redis/index.cjs.map +0 -1
  189. package/dist/topic-redis/index.d.cts +0 -42
  190. package/dist/vite/index.cjs +0 -1077
  191. package/dist/vite/index.cjs.map +0 -1
  192. package/dist/vite/index.d.cts +0 -542
  193. package/dist/websocket/index.cjs +0 -1117
  194. package/dist/websocket/index.cjs.map +0 -1
  195. 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