brix-runtime-sdk-api-web 1.0.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 (135) hide show
  1. package/dist/index.js +190 -0
  2. package/dist/types/api-exports.test.d.ts +33 -0
  3. package/dist/types/api-exports.test.d.ts.map +1 -0
  4. package/dist/types/context/RuntimeContext.d.ts +69 -0
  5. package/dist/types/context/RuntimeContext.d.ts.map +1 -0
  6. package/dist/types/context/index.d.ts +23 -0
  7. package/dist/types/context/index.d.ts.map +1 -0
  8. package/dist/types/index.d.ts +52 -0
  9. package/dist/types/index.d.ts.map +1 -0
  10. package/dist/types/types/auth.d.ts +405 -0
  11. package/dist/types/types/auth.d.ts.map +1 -0
  12. package/dist/types/types/capability.d.ts +218 -0
  13. package/dist/types/types/capability.d.ts.map +1 -0
  14. package/dist/types/types/common.d.ts +99 -0
  15. package/dist/types/types/common.d.ts.map +1 -0
  16. package/dist/types/types/config.d.ts +85 -0
  17. package/dist/types/types/config.d.ts.map +1 -0
  18. package/dist/types/types/event.d.ts +658 -0
  19. package/dist/types/types/event.d.ts.map +1 -0
  20. package/dist/types/types/http.d.ts +132 -0
  21. package/dist/types/types/http.d.ts.map +1 -0
  22. package/dist/types/types/i18n.d.ts +327 -0
  23. package/dist/types/types/i18n.d.ts.map +1 -0
  24. package/dist/types/types/index.d.ts +61 -0
  25. package/dist/types/types/index.d.ts.map +1 -0
  26. package/dist/types/types/layout.d.ts +301 -0
  27. package/dist/types/types/layout.d.ts.map +1 -0
  28. package/dist/types/types/module.d.ts +78 -0
  29. package/dist/types/types/module.d.ts.map +1 -0
  30. package/dist/types/types/navigation.d.ts +295 -0
  31. package/dist/types/types/navigation.d.ts.map +1 -0
  32. package/dist/types/types/plugin-loader-capability.d.ts +142 -0
  33. package/dist/types/types/plugin-loader-capability.d.ts.map +1 -0
  34. package/dist/types/types/plugin.d.ts +250 -0
  35. package/dist/types/types/plugin.d.ts.map +1 -0
  36. package/dist/types/types/state.d.ts +306 -0
  37. package/dist/types/types/state.d.ts.map +1 -0
  38. package/dist/types/types/theme.d.ts +279 -0
  39. package/dist/types/types/theme.d.ts.map +1 -0
  40. package/dist/types/types/ui/adapter.d.ts +181 -0
  41. package/dist/types/types/ui/adapter.d.ts.map +1 -0
  42. package/dist/types/types/ui/avatar.d.ts +102 -0
  43. package/dist/types/types/ui/avatar.d.ts.map +1 -0
  44. package/dist/types/types/ui/badge.d.ts +101 -0
  45. package/dist/types/types/ui/badge.d.ts.map +1 -0
  46. package/dist/types/types/ui/button.d.ts +135 -0
  47. package/dist/types/types/ui/button.d.ts.map +1 -0
  48. package/dist/types/types/ui/card.d.ts +105 -0
  49. package/dist/types/types/ui/card.d.ts.map +1 -0
  50. package/dist/types/types/ui/common.d.ts +29 -0
  51. package/dist/types/types/ui/common.d.ts.map +1 -0
  52. package/dist/types/types/ui/icon.d.ts +78 -0
  53. package/dist/types/types/ui/icon.d.ts.map +1 -0
  54. package/dist/types/types/ui/index.d.ts +59 -0
  55. package/dist/types/types/ui/index.d.ts.map +1 -0
  56. package/dist/types/types/ui/input.d.ts +200 -0
  57. package/dist/types/types/ui/input.d.ts.map +1 -0
  58. package/dist/types/types/ui/menu.d.ts +211 -0
  59. package/dist/types/types/ui/menu.d.ts.map +1 -0
  60. package/dist/types/types/ui/message.d.ts +121 -0
  61. package/dist/types/types/ui/message.d.ts.map +1 -0
  62. package/dist/types/types/ui/modal.d.ts +167 -0
  63. package/dist/types/types/ui/modal.d.ts.map +1 -0
  64. package/dist/types/types/ui/select.d.ts +213 -0
  65. package/dist/types/types/ui/select.d.ts.map +1 -0
  66. package/dist/types/types/ui/theme-tokens.d.ts +226 -0
  67. package/dist/types/types/ui/theme-tokens.d.ts.map +1 -0
  68. package/dist/types/types/ui/tooltip.d.ts +98 -0
  69. package/dist/types/types/ui/tooltip.d.ts.map +1 -0
  70. package/dist/types/types/ui.d.ts +49 -0
  71. package/dist/types/types/ui.d.ts.map +1 -0
  72. package/package.json +34 -0
  73. package/src/api-exports.test.ts +199 -0
  74. package/src/context/RuntimeContext.d.ts +69 -0
  75. package/src/context/RuntimeContext.d.ts.map +1 -0
  76. package/src/context/RuntimeContext.ts +75 -0
  77. package/src/context/index.d.ts +23 -0
  78. package/src/context/index.d.ts.map +1 -0
  79. package/src/context/index.ts +23 -0
  80. package/src/index.d.ts +52 -0
  81. package/src/index.d.ts.map +1 -0
  82. package/src/index.ts +59 -0
  83. package/src/types/auth.d.ts +146 -0
  84. package/src/types/auth.d.ts.map +1 -0
  85. package/src/types/auth.ts +479 -0
  86. package/src/types/capability.d.ts +218 -0
  87. package/src/types/capability.d.ts.map +1 -0
  88. package/src/types/capability.ts +302 -0
  89. package/src/types/common.d.ts +99 -0
  90. package/src/types/common.d.ts.map +1 -0
  91. package/src/types/common.ts +115 -0
  92. package/src/types/config.d.ts +64 -0
  93. package/src/types/config.d.ts.map +1 -0
  94. package/src/types/config.ts +96 -0
  95. package/src/types/event.d.ts +206 -0
  96. package/src/types/event.d.ts.map +1 -0
  97. package/src/types/event.ts +776 -0
  98. package/src/types/http.d.ts +132 -0
  99. package/src/types/http.d.ts.map +1 -0
  100. package/src/types/http.ts +156 -0
  101. package/src/types/i18n.ts +420 -0
  102. package/src/types/index.d.ts +50 -0
  103. package/src/types/index.d.ts.map +1 -0
  104. package/src/types/index.ts +120 -0
  105. package/src/types/layout.ts +394 -0
  106. package/src/types/module.d.ts +78 -0
  107. package/src/types/module.d.ts.map +1 -0
  108. package/src/types/module.ts +92 -0
  109. package/src/types/navigation.d.ts +101 -0
  110. package/src/types/navigation.d.ts.map +1 -0
  111. package/src/types/navigation.ts +361 -0
  112. package/src/types/plugin-loader-capability.ts +159 -0
  113. package/src/types/plugin.d.ts +250 -0
  114. package/src/types/plugin.d.ts.map +1 -0
  115. package/src/types/plugin.ts +344 -0
  116. package/src/types/state.d.ts +119 -0
  117. package/src/types/state.d.ts.map +1 -0
  118. package/src/types/state.ts +366 -0
  119. package/src/types/theme.ts +378 -0
  120. package/src/types/ui/adapter.ts +222 -0
  121. package/src/types/ui/avatar.ts +113 -0
  122. package/src/types/ui/badge.ts +112 -0
  123. package/src/types/ui/button.ts +148 -0
  124. package/src/types/ui/card.ts +116 -0
  125. package/src/types/ui/common.ts +29 -0
  126. package/src/types/ui/icon.ts +85 -0
  127. package/src/types/ui/index.ts +78 -0
  128. package/src/types/ui/input.ts +225 -0
  129. package/src/types/ui/menu.ts +237 -0
  130. package/src/types/ui/message.ts +135 -0
  131. package/src/types/ui/modal.ts +188 -0
  132. package/src/types/ui/select.ts +239 -0
  133. package/src/types/ui/theme-tokens.ts +357 -0
  134. package/src/types/ui/tooltip.ts +120 -0
  135. package/src/types/ui.ts +49 -0
@@ -0,0 +1,658 @@
1
+ /**
2
+ * Copyright 2026 Brix Platform Authors
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ */
16
+ /**
17
+ * @file Event-Related Type Definitions
18
+ * @description Defines core types for the event system, including event messages, handlers, subscription options, etc.
19
+ * @module @brix/runtime-sdk-api-web/types/event
20
+ * @version 3.3.0
21
+ *
22
+ * [v3.3 Changes - Phase 3 Contract Layer Cleanup]
23
+ * - Migrated BaseEvent, MetadataEvent from platform-shared to runtime-sdk-api-web (LL3 compliance)
24
+ * - Added EventPriority, EventSubscriptionOptions, EventPublishOptions contract types
25
+ * - runtime-sdk-api-web is now the authoritative source for all event contract types
26
+ *
27
+ * [v3.2 Changes]
28
+ * Extracted from index.ts into a standalone type file.
29
+ *
30
+ * [Design Principles]
31
+ * - Supports both simple Event Bus and Governed Event Bus modes
32
+ * - Governed Event Bus provides complete event metadata and audit information
33
+ * - All event-related contract types are defined here (single source of truth)
34
+ */
35
+ /**
36
+ * Base Event Interface
37
+ *
38
+ * <p>Defines the common fields for all events in the Brix Platform.
39
+ * This is the foundational contract type for the event system.</p>
40
+ *
41
+ * <h3>Design Rationale</h3>
42
+ * <ul>
43
+ * <li>Provides minimal required fields for event identification</li>
44
+ * <li>Extensible through interface inheritance</li>
45
+ * <li>Platform-agnostic (works on Web/Mobile/Server)</li>
46
+ * </ul>
47
+ *
48
+ * <h3>Usage Example</h3>
49
+ * ```typescript
50
+ * interface UserCreatedEvent extends BaseEvent {
51
+ * type: 'user:created';
52
+ * userId: string;
53
+ * email: string;
54
+ * }
55
+ * ```
56
+ *
57
+ * @since 3.3.0 Migrated from platform-shared (LL3 compliance)
58
+ */
59
+ export interface BaseEvent {
60
+ /**
61
+ * Event type identifier
62
+ *
63
+ * <p>Follows the convention: `{domain}:{action}` (e.g., 'user:created', 'booking:confirmed').</p>
64
+ */
65
+ readonly type: string;
66
+ /**
67
+ * Event timestamp in milliseconds (Unix epoch)
68
+ *
69
+ * <p>Represents when the event was created/emitted.</p>
70
+ */
71
+ readonly timestamp: number;
72
+ /**
73
+ * Event source identifier (typically plugin ID)
74
+ *
75
+ * <p>Identifies which plugin or system component emitted the event.</p>
76
+ */
77
+ readonly source?: string;
78
+ }
79
+ /**
80
+ * Event with Metadata
81
+ *
82
+ * <p>Extends BaseEvent with rich metadata for observability, auditing, and governance.
83
+ * Used in scenarios requiring event tracing, multi-tenancy support, or detailed logging.</p>
84
+ *
85
+ * <h3>Relationship with Other Event Types</h3>
86
+ * <ul>
87
+ * <li>{@link BaseEvent}: Minimal event contract</li>
88
+ * <li>{@link MetadataEvent}: Extended with observability metadata (this interface)</li>
89
+ * <li>{@link GovernedEvent}: Full governance support with strict typing</li>
90
+ * </ul>
91
+ *
92
+ * <h3>Usage Example</h3>
93
+ * ```typescript
94
+ * const event: MetadataEvent = {
95
+ * type: 'order:placed',
96
+ * timestamp: Date.now(),
97
+ * source: 'plugin-orders',
98
+ * metadata: {
99
+ * sourcePlugin: 'plugin-orders',
100
+ * scope: 'host',
101
+ * traceId: 'trace-123',
102
+ * timestamp: Date.now(),
103
+ * tenantId: 'tenant-abc'
104
+ * }
105
+ * };
106
+ * ```
107
+ *
108
+ * @since 3.3.0 Migrated from platform-shared (LL3 compliance)
109
+ */
110
+ export interface MetadataEvent extends BaseEvent {
111
+ /**
112
+ * Event metadata for observability and governance
113
+ *
114
+ * <p>Contains tracing information, tenant context, and scope designation.</p>
115
+ */
116
+ readonly metadata: EventMetadata;
117
+ }
118
+ /**
119
+ * Event Priority Levels
120
+ *
121
+ * <p>Defines the priority levels for event processing order.
122
+ * Higher priority events are processed before lower priority ones.</p>
123
+ *
124
+ * <h3>Priority Semantics</h3>
125
+ * <ul>
126
+ * <li>`low`: Background tasks, analytics, non-critical updates</li>
127
+ * <li>`normal`: Standard business events (default)</li>
128
+ * <li>`high`: Important business events requiring prompt processing</li>
129
+ * <li>`critical`: System-critical events, error handling, security alerts</li>
130
+ * </ul>
131
+ *
132
+ * @since 3.3.0 Migrated from platform-shared (LL3 compliance)
133
+ */
134
+ export type EventPriority = 'low' | 'normal' | 'high' | 'critical';
135
+ /**
136
+ * Event Subscription Options (Extended)
137
+ *
138
+ * <p>Configuration options for event subscription with priority and filtering support.
139
+ * Extends the basic {@link SubscriptionOptions} with additional capabilities.</p>
140
+ *
141
+ * <h3>Relationship with SubscriptionOptions</h3>
142
+ * <ul>
143
+ * <li>{@link SubscriptionOptions}: Basic subscription options (once, filter)</li>
144
+ * <li>{@link EventSubscriptionOptions}: Extended options with priority support</li>
145
+ * </ul>
146
+ *
147
+ * <h3>Usage Example</h3>
148
+ * ```typescript
149
+ * eventBus.on('user:action', handler, {
150
+ * priority: 'high',
151
+ * once: false,
152
+ * filter: (event) => event.userId === currentUserId
153
+ * });
154
+ * ```
155
+ *
156
+ * @since 3.3.0 Migrated from platform-shared (LL3 compliance)
157
+ */
158
+ export interface EventSubscriptionOptions {
159
+ /**
160
+ * Whether to trigger only once
161
+ *
162
+ * <p>If true, the handler is automatically unsubscribed after first invocation.</p>
163
+ */
164
+ readonly once?: boolean;
165
+ /**
166
+ * Subscription priority
167
+ *
168
+ * <p>Determines the order in which handlers are invoked.
169
+ * Higher priority handlers are called before lower priority ones.</p>
170
+ *
171
+ * @default 'normal'
172
+ */
173
+ readonly priority?: EventPriority;
174
+ /**
175
+ * Filter function for selective event handling
176
+ *
177
+ * <p>If provided, the handler is only invoked when the filter returns true.</p>
178
+ *
179
+ * @param event The event payload
180
+ * @returns Whether to invoke the handler
181
+ */
182
+ readonly filter?: (event: unknown) => boolean;
183
+ }
184
+ /**
185
+ * Event Publish Options
186
+ *
187
+ * <p>Configuration options for event publishing behavior.
188
+ * Supports async/sync modes, delayed emission, and rate limiting.</p>
189
+ *
190
+ * <h3>Usage Example</h3>
191
+ * ```typescript
192
+ * eventBus.emit('analytics:track', payload, {
193
+ * async: true,
194
+ * debounce: 300,
195
+ * tags: ['analytics', 'user-action']
196
+ * });
197
+ * ```
198
+ *
199
+ * @since 3.3.0 Migrated from platform-shared (LL3 compliance)
200
+ */
201
+ export interface EventPublishOptions {
202
+ /**
203
+ * Whether to emit asynchronously
204
+ *
205
+ * <p>If true, the event is queued and emitted in the next microtask.
206
+ * If false, handlers are invoked synchronously.</p>
207
+ *
208
+ * @default true
209
+ */
210
+ readonly async?: boolean;
211
+ /**
212
+ * Delay before emission in milliseconds
213
+ *
214
+ * <p>If specified, the event emission is delayed by this amount.</p>
215
+ */
216
+ readonly delay?: number;
217
+ /**
218
+ * Debounce interval in milliseconds
219
+ *
220
+ * <p>If specified, rapid emissions of the same event type are debounced.
221
+ * Only the last emission within the interval is actually sent.</p>
222
+ */
223
+ readonly debounce?: number;
224
+ /**
225
+ * Throttle interval in milliseconds
226
+ *
227
+ * <p>If specified, emissions are throttled to at most one per interval.</p>
228
+ */
229
+ readonly throttle?: number;
230
+ }
231
+ /**
232
+ * Event Message
233
+ *
234
+ * <p>Encapsulates complete event information including type, payload, timestamp, and source.</p>
235
+ */
236
+ export interface EventMessage<T = unknown> {
237
+ /** Event Type */
238
+ readonly eventType: string;
239
+ /** Event Payload */
240
+ readonly payload: T;
241
+ /** Timestamp */
242
+ readonly timestamp: number;
243
+ /** Event Source (Plugin ID) */
244
+ readonly source?: string;
245
+ }
246
+ /**
247
+ * Event Subscription Options
248
+ */
249
+ export interface SubscriptionOptions {
250
+ /** Whether to trigger only once */
251
+ readonly once?: boolean;
252
+ /** Filter function */
253
+ readonly filter?: (payload: unknown) => boolean;
254
+ }
255
+ /**
256
+ * Event Handler
257
+ *
258
+ * @typeParam T - Event payload type
259
+ */
260
+ export type EventHandler<T = unknown> = (payload: T) => void;
261
+ /**
262
+ * Unsubscribe Function
263
+ */
264
+ export type Unsubscribe = () => void;
265
+ /**
266
+ * Event Bus Capability Type Identifier
267
+ */
268
+ export declare const EventBusCapabilityType: unique symbol;
269
+ /**
270
+ * Event Bus Capability Contract
271
+ *
272
+ * <p>Provides cross-plugin communication capability for plugins.</p>
273
+ *
274
+ * <h3>Usage Example</h3>
275
+ * ```typescript
276
+ * const eventBus = context.getCapability<EventBusCapability>(EventBusCapabilityType);
277
+ *
278
+ * // Emit event
279
+ * eventBus.emit('booking:selected', { bookingId: '123' });
280
+ *
281
+ * // Subscribe to event
282
+ * const unsubscribe = eventBus.on('booking:selected', (payload) => {
283
+ * console.log('Booking selected:', payload);
284
+ * });
285
+ * ```
286
+ */
287
+ export interface EventBusCapability {
288
+ /**
289
+ * Emit event
290
+ *
291
+ * @param eventType Event type
292
+ * @param payload Event payload
293
+ */
294
+ emit(eventType: string, payload: unknown): void;
295
+ /**
296
+ * Subscribe to event
297
+ *
298
+ * @param eventType Event type
299
+ * @param handler Event handler
300
+ * @returns Unsubscribe function
301
+ */
302
+ on(eventType: string, handler: EventHandler): () => void;
303
+ /**
304
+ * Unsubscribe from event
305
+ *
306
+ * @param eventType Event type
307
+ * @param handler Event handler
308
+ */
309
+ off(eventType: string, handler: EventHandler): void;
310
+ }
311
+ /**
312
+ * Governed Event Bus Capability Type Identifier
313
+ */
314
+ export declare const GovernedEventBusCapabilityType: unique symbol;
315
+ /**
316
+ * Governed Event
317
+ *
318
+ * <p>Event containing complete metadata for observability and auditing.</p>
319
+ */
320
+ export interface GovernedEvent<T = unknown> {
321
+ /** Event Type */
322
+ readonly type: string;
323
+ /** Event Payload */
324
+ readonly payload: T;
325
+ /** Event Metadata */
326
+ readonly metadata: GovernedEventMetadata;
327
+ }
328
+ /**
329
+ * Governed Event Metadata
330
+ */
331
+ export interface GovernedEventMetadata {
332
+ /** Event ID (Unique Identifier) */
333
+ readonly eventId: string;
334
+ /** Emit Timestamp */
335
+ readonly timestamp: number;
336
+ /** Sender (Plugin ID) */
337
+ readonly source: string;
338
+ /** Tenant ID */
339
+ readonly tenantId?: string;
340
+ /**
341
+ * Event Scope
342
+ * - 'plugin': Visible only within the plugin
343
+ * - 'host': Globally visible
344
+ */
345
+ readonly scope: 'plugin' | 'host';
346
+ }
347
+ /**
348
+ * Event Metadata
349
+ *
350
+ * <p>Extended metadata for Web-side event tracking and observability.
351
+ * Compared to GovernedEventMetadata, provides more flexible field naming for Web scenarios.</p>
352
+ *
353
+ * <h3>Relationship with GovernedEventMetadata</h3>
354
+ * <ul>
355
+ * <li>GovernedEventMetadata: Used for Governed Event Bus</li>
356
+ * <li>EventMetadata: Used for general event emission scenarios</li>
357
+ * </ul>
358
+ *
359
+ * @since 3.2.0
360
+ */
361
+ export interface EventMetadata {
362
+ /** Sender Plugin ID */
363
+ readonly sourcePlugin: string;
364
+ /**
365
+ * Event Scope
366
+ * - 'plugin': Visible only within the plugin
367
+ * - 'host': Globally visible (cross-plugin)
368
+ */
369
+ readonly scope: 'plugin' | 'host';
370
+ /** Trace ID (for distributed tracing) */
371
+ readonly traceId: string;
372
+ /** Emit Timestamp (milliseconds) */
373
+ readonly timestamp: number;
374
+ /** Tenant ID (multi-tenant scenario) */
375
+ readonly tenantId?: string;
376
+ /** Custom Tags (for filtering and classification) */
377
+ readonly tags?: ReadonlyArray<string>;
378
+ }
379
+ /**
380
+ * Web Event Emit Options
381
+ *
382
+ * <p>Configuration parameters controlling event emission behavior.</p>
383
+ *
384
+ * @since 3.2.0
385
+ */
386
+ export interface WebEventEmitOptions {
387
+ /**
388
+ * Event Scope
389
+ * - 'plugin': Visible only within the current plugin
390
+ * - 'host': Globally visible, can be subscribed across plugins
391
+ * @default 'host'
392
+ */
393
+ readonly scope?: 'plugin' | 'host';
394
+ /**
395
+ * Whether to emit synchronously
396
+ *
397
+ * <p>Default is asynchronous (via queueMicrotask),
398
+ * set to true to immediately invoke all subscribers synchronously.</p>
399
+ *
400
+ * @default false
401
+ */
402
+ readonly sync?: boolean;
403
+ /**
404
+ * Custom Tags
405
+ *
406
+ * <p>Used for event classification and filtering, visible in logs and monitoring.</p>
407
+ */
408
+ readonly tags?: ReadonlyArray<string>;
409
+ }
410
+ /**
411
+ * Backpressure Overflow Strategy
412
+ *
413
+ * <p>Defines behavior when event queue reaches maxQueueDepth.</p>
414
+ *
415
+ * @since 3.3.0
416
+ */
417
+ export type BackpressureOverflowStrategy =
418
+ /**
419
+ * Drop oldest events to make room for new ones
420
+ * 丢弃最旧的事件以为新事件腾出空间
421
+ */
422
+ 'drop-oldest'
423
+ /**
424
+ * Reject new events when queue is full (throws BackpressureError)
425
+ * 队列满时拒绝新事件(抛出 BackpressureError)
426
+ */
427
+ | 'reject'
428
+ /**
429
+ * Block the emit call until space is available (async only)
430
+ * 阻塞 emit 调用直到有空间可用(仅异步)
431
+ */
432
+ | 'block';
433
+ /**
434
+ * Backpressure Configuration
435
+ *
436
+ * <p>Configuration for event bus backpressure management.
437
+ * Prevents memory exhaustion and ensures system stability under high load.</p>
438
+ *
439
+ * 事件总线背压管理配置。
440
+ * 防止内存耗尽,确保高负载下的系统稳定性。
441
+ *
442
+ * @since 3.3.0
443
+ */
444
+ export interface BackpressureConfig {
445
+ /**
446
+ * Maximum queue depth per event type
447
+ *
448
+ * <p>When the number of pending events exceeds this limit,
449
+ * the overflow strategy is applied.</p>
450
+ *
451
+ * 每个事件类型的最大队列深度。
452
+ * 当待处理事件数量超过此限制时,将应用溢出策略。
453
+ *
454
+ * @default 1000
455
+ */
456
+ readonly maxQueueDepth?: number;
457
+ /**
458
+ * Global maximum queue depth (across all event types)
459
+ *
460
+ * 全局最大队列深度(跨所有事件类型)
461
+ *
462
+ * @default 10000
463
+ */
464
+ readonly globalMaxQueueDepth?: number;
465
+ /**
466
+ * Overflow strategy when queue is full
467
+ *
468
+ * 队列满时的溢出策略
469
+ *
470
+ * @default 'drop-oldest'
471
+ */
472
+ readonly overflowStrategy?: BackpressureOverflowStrategy;
473
+ /**
474
+ * Warning threshold percentage (0-100)
475
+ *
476
+ * <p>Emits a warning event when queue reaches this percentage of maxQueueDepth.</p>
477
+ *
478
+ * 警告阈值百分比。当队列达到 maxQueueDepth 的此百分比时发出警告事件。
479
+ *
480
+ * @default 80
481
+ */
482
+ readonly warningThreshold?: number;
483
+ /**
484
+ * Enable backpressure metrics collection
485
+ *
486
+ * 启用背压指标收集
487
+ *
488
+ * @default true
489
+ */
490
+ readonly enableMetrics?: boolean;
491
+ }
492
+ /**
493
+ * Backpressure Metrics
494
+ *
495
+ * <p>Runtime metrics for monitoring backpressure state.</p>
496
+ *
497
+ * @since 3.3.0
498
+ */
499
+ export interface BackpressureMetrics {
500
+ /** Current queue depth per event type */
501
+ readonly queueDepthByType: ReadonlyMap<string, number>;
502
+ /** Total events in queue */
503
+ readonly totalQueueDepth: number;
504
+ /** Number of events dropped due to backpressure */
505
+ readonly droppedCount: number;
506
+ /** Number of events rejected due to backpressure */
507
+ readonly rejectedCount: number;
508
+ /** Number of times warning threshold was reached */
509
+ readonly warningCount: number;
510
+ /** Last warning timestamp */
511
+ readonly lastWarningTimestamp?: number;
512
+ /** Queue utilization percentage (0-100) */
513
+ readonly utilizationPercent: number;
514
+ }
515
+ /**
516
+ * Backpressure Error
517
+ *
518
+ * <p>Thrown when event is rejected due to backpressure.</p>
519
+ *
520
+ * @since 3.3.0
521
+ */
522
+ export declare class BackpressureError extends Error {
523
+ readonly eventType: string;
524
+ readonly queueDepth: number;
525
+ readonly maxQueueDepth: number;
526
+ constructor(eventType: string, queueDepth: number, maxQueueDepth: number);
527
+ }
528
+ /**
529
+ * Web Event Subscribe Options
530
+ *
531
+ * <p>Configuration parameters controlling event subscription behavior.</p>
532
+ *
533
+ * @since 3.2.0
534
+ */
535
+ export interface WebEventSubscribeOptions {
536
+ /**
537
+ * Debounce Time (milliseconds)
538
+ *
539
+ * <p>For consecutive events triggered in a short time, only the last one is processed.</p>
540
+ */
541
+ readonly debounce?: number;
542
+ /**
543
+ * Throttle Time (milliseconds)
544
+ *
545
+ * <p>Limits the minimum time interval between event processing.</p>
546
+ */
547
+ readonly throttle?: number;
548
+ /**
549
+ * Event Filter
550
+ *
551
+ * <p>Handler is called only when this returns true.</p>
552
+ */
553
+ readonly filter?: (payload: unknown) => boolean;
554
+ /**
555
+ * Whether to trigger only once
556
+ *
557
+ * @default false
558
+ */
559
+ readonly once?: boolean;
560
+ }
561
+ /**
562
+ * Governed Event Handler Function
563
+ */
564
+ export type GovernedEventHandler<T = unknown> = (event: GovernedEvent<T>) => void;
565
+ /**
566
+ * Governed Event Bus Capability Contract
567
+ *
568
+ * <p>Unlike the simple EventBusCapability, GovernedEventBusCapability provides:</p>
569
+ * <ul>
570
+ * <li>Automatic injection of event metadata (eventId, timestamp, source)</li>
571
+ * <li>Event scope control (plugin/host)</li>
572
+ * <li>Complete event audit information</li>
573
+ * </ul>
574
+ *
575
+ * <h3>Usage Example</h3>
576
+ * ```typescript
577
+ * const eventBus = context.getCapability<GovernedEventBusCapability>(GovernedEventBusCapabilityType);
578
+ *
579
+ * // Emit global event
580
+ * eventBus.emit('booking:created', { bookingId: '123' }, 'host');
581
+ *
582
+ * // Subscribe to event (receive complete metadata)
583
+ * eventBus.on('booking:created', (event) => {
584
+ * console.log(`Event ${event.metadata.eventId} from ${event.metadata.source}`);
585
+ * console.log('Payload:', event.payload);
586
+ * });
587
+ * ```
588
+ */
589
+ export interface GovernedEventBusCapability {
590
+ /**
591
+ * Emit Event
592
+ *
593
+ * @param eventType Event type
594
+ * @param payload Event payload
595
+ * @param scope Event scope (default 'host')
596
+ */
597
+ emit<T = unknown>(eventType: string, payload: T, scope?: 'plugin' | 'host'): void;
598
+ /**
599
+ * Subscribe to Event
600
+ *
601
+ * @param eventType Event type
602
+ * @param handler Event handler function, receives complete GovernedEvent
603
+ * @returns Unsubscribe function
604
+ */
605
+ on<T = unknown>(eventType: string, handler: GovernedEventHandler<T>): Unsubscribe;
606
+ /**
607
+ * Subscribe to Event Once
608
+ *
609
+ * @param eventType Event type
610
+ * @param handler Event handler function
611
+ * @returns Unsubscribe function
612
+ */
613
+ once<T = unknown>(eventType: string, handler: GovernedEventHandler<T>): Unsubscribe;
614
+ /**
615
+ * Unsubscribe from Event
616
+ *
617
+ * @param eventType Event type
618
+ * @param handler Event handler function
619
+ */
620
+ off<T = unknown>(eventType: string, handler: GovernedEventHandler<T>): void;
621
+ /**
622
+ * Configure backpressure settings
623
+ *
624
+ * 配置背压设置
625
+ *
626
+ * @param config Backpressure configuration
627
+ * @since 3.3.0
628
+ */
629
+ configureBackpressure?(config: BackpressureConfig): void;
630
+ /**
631
+ * Get current backpressure metrics
632
+ *
633
+ * 获取当前背压指标
634
+ *
635
+ * @returns Current backpressure metrics
636
+ * @since 3.3.0
637
+ */
638
+ getBackpressureMetrics?(): BackpressureMetrics;
639
+ /**
640
+ * Check if backpressure is active for an event type
641
+ *
642
+ * 检查某事件类型是否处于背压状态
643
+ *
644
+ * @param eventType Event type to check
645
+ * @returns True if backpressure is active
646
+ * @since 3.3.0
647
+ */
648
+ isBackpressureActive?(eventType?: string): boolean;
649
+ /**
650
+ * Reset backpressure metrics
651
+ *
652
+ * 重置背压指标
653
+ *
654
+ * @since 3.3.0
655
+ */
656
+ resetBackpressureMetrics?(): void;
657
+ }
658
+ //# sourceMappingURL=event.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../../src/types/event.ts"],"names":[],"mappings":"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"}