@fluojs/event-bus 1.0.0-beta.3 → 1.0.0-beta.4

package/README.ko.md

@@ -75,6 +75,8 @@ export class UserService {
 }
 ```
 
+`publish(event, options?)`는 `signal`, `timeoutMs`, `waitForHandlers`를 지원합니다. `waitForHandlers`의 기본값은 `true`이며, `false`로 설정하면 publish가 즉시 반환되고 timeout bound를 적용하지 않습니다.
+
 ## 일반적인 패턴
 
 ### 분산 팬아웃 (Redis)
@@ -102,11 +104,13 @@ class UserRegisteredEvent {
 }
 ```
 
+핸들러는 imported module의 singleton provider와 controller에서 발견됩니다. 각 핸들러는 격리된 clone payload를 받으며, class inheritance는 `instanceof` 매칭으로 지원됩니다.
+
 ## 공개 API 개요
 
 ### 핵심 구성 요소
 - `EventBusModule.forRoot(...)`: 이벤트 버스 등록을 위한 기본 진입점입니다.
-- `EventBusLifecycleService`: 이벤트를 발행(`publish(event)`)하기 위한 기본 서비스입니다.
+- `EventBusLifecycleService`: 이벤트 발행(`publish(event, options?)`)과 platform status snapshot 생성을 위한 기본 서비스입니다.
 - `@OnEvent(EventClass)`: 특정 메서드를 이벤트 핸들러로 지정하는 데코레이터입니다.
 - `EVENT_BUS`: 발행 facade를 위한 호환성 주입 토큰입니다.
 - `createEventBusPlatformStatusSnapshot(...)`: diagnostics와 health surface에서 사용하는 상태 스냅샷 헬퍼입니다.
@@ -114,6 +118,9 @@ class UserRegisteredEvent {
 ### 인터페이스
 - `EventBusTransport`: 외부 트랜스포트 어댑터 구현을 위한 계약입니다.
 - `EventBus`, `EventPublishOptions`, `EventBusModuleOptions`, `EventType`: 발행, 기본값, 트랜스포트, 안정적인 이벤트 키를 위한 타입 전용 계약입니다.
+- `EventBusLifecycleState`, `EventBusStatusAdapterInput`, `EventBusPlatformStatusSnapshot`: status snapshot 계약입니다.
+
+Transport bootstrap은 unique event channel마다 한 번만 subscribe합니다. `eventKey`가 있으면 transport channel 이름을 제어합니다. 잘못된 JSON transport message는 무시됩니다.
 
 ## 런타임별 및 통합 서브패스
 
@@ -132,3 +139,5 @@ class UserRegisteredEvent {
 
 - `packages/event-bus/src/module.test.ts`: 핸들러 탐색 및 발행/구독 테스트 예제.
 - `packages/event-bus/src/public-surface.test.ts`: 공개 API 계약 검증 예제.
+- `packages/event-bus/src/status.test.ts`: status snapshot semantic 테스트 예제.
+- `packages/event-bus/src/transports/redis-transport.test.ts`: Redis transport 동작 테스트 예제.

package/README.md

@@ -75,6 +75,8 @@ export class UserService {
 }
 ```
 
+`publish(event, options?)` supports `signal`, `timeoutMs`, and `waitForHandlers`. `waitForHandlers` defaults to `true`; when set to `false`, publishing returns immediately and skips timeout bounds.
+
 ## Common Patterns
 
 ### Distributed Fan-out (Redis)
@@ -102,11 +104,13 @@ class UserRegisteredEvent {
 }
 ```
 
+Handlers are discovered from singleton providers and controllers across imported modules. Each handler receives an isolated cloned payload, and class inheritance is supported through `instanceof` matching.
+
 ## Public API Overview
 
 ### Core
 - `EventBusModule.forRoot(...)`: Main entry point for event bus registration.
-- `EventBusLifecycleService`: Primary service for publishing events (`publish(event)`).
+- `EventBusLifecycleService`: Primary service for publishing events (`publish(event, options?)`) and creating platform status snapshots.
 - `@OnEvent(EventClass)`: Decorator to mark a method as an event handler.
 - `EVENT_BUS`: Compatibility injection token for the publish facade.
 - `createEventBusPlatformStatusSnapshot(...)`: Status snapshot helper used by diagnostics and health surfaces.
@@ -114,6 +118,9 @@ class UserRegisteredEvent {
 ### Interfaces
 - `EventBusTransport`: Contract for implementing external transport adapters.
 - `EventBus`, `EventPublishOptions`, `EventBusModuleOptions`, `EventType`: Type-only contracts for publishing, defaults, transports, and stable event keys.
+- `EventBusLifecycleState`, `EventBusStatusAdapterInput`, `EventBusPlatformStatusSnapshot`: Status snapshot contracts.
+
+Transport bootstrap subscribes once per unique event channel. `eventKey` controls the transport channel name when present. Invalid JSON transport messages are ignored.
 
 ## Runtime-Specific and Integration Subpaths
 
@@ -132,3 +139,5 @@ class UserRegisteredEvent {
 
 - `packages/event-bus/src/module.test.ts`: Handler discovery and publish/subscribe tests.
 - `packages/event-bus/src/public-surface.test.ts`: Public API contract verification.
+- `packages/event-bus/src/status.test.ts`: Status snapshot semantics.
+- `packages/event-bus/src/transports/redis-transport.test.ts`: Redis transport behavior.

package/dist/decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAwB,SAAS,EAAE,MAAM,YAAY,CAAC;AAIlE,KAAK,yBAAyB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;AACjG,KAAK,mBAAmB,GAAG,yBAAyB,CAAC;AAqBrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,mBAAmB,CAkBjE"}
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAwB,SAAS,EAAE,MAAM,YAAY,CAAC;AAIlE,KAAK,yBAAyB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;AACjG,KAAK,mBAAmB,GAAG,yBAAyB,CAAC;AAsBrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,mBAAmB,CAkBjE"}

package/dist/decorators.js

@@ -1,7 +1,7 @@
-import { metadataSymbol } from '@fluojs/core/internal';
+import { ensureMetadataSymbol } from '@fluojs/core/internal';
 import { eventBusMetadataSymbol } from './metadata.js';
+ensureMetadataSymbol();
 function getStandardMetadataBag(metadata) {
-  void metadataSymbol;
   return metadata;
 }
 function defineStandardEventHandlerMetadata(metadata, propertyKey, eventHandlerMetadata) {

package/dist/metadata.d.ts

@@ -1,10 +1,33 @@
 import { type MetadataPropertyKey } from '@fluojs/core';
 import type { EventHandlerMetadata } from './types.js';
+/**
+ * Define event handler metadata.
+ *
+ * @param target The target.
+ * @param propertyKey The property key.
+ * @param metadata The metadata.
+ */
 export declare function defineEventHandlerMetadata(target: object, propertyKey: MetadataPropertyKey, metadata: EventHandlerMetadata): void;
+/**
+ * Get event handler metadata.
+ *
+ * @param target The target.
+ * @param propertyKey The property key.
+ * @returns The get event handler metadata result.
+ */
 export declare function getEventHandlerMetadata(target: object, propertyKey: MetadataPropertyKey): EventHandlerMetadata | undefined;
+/**
+ * Get event handler metadata entries.
+ *
+ * @param target The target.
+ * @returns The get event handler metadata entries result.
+ */
 export declare function getEventHandlerMetadataEntries(target: object): Array<{
     metadata: EventHandlerMetadata;
     propertyKey: MetadataPropertyKey;
 }>;
+/**
+ * Provides the event bus metadata symbol value.
+ */
 export declare const eventBusMetadataSymbol: symbol;
 //# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AA8BvD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,mBAAmB,EAChC,QAAQ,EAAE,oBAAoB,GAC7B,IAAI,CAEN;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,GAAG,oBAAoB,GAAG,SAAS,CAS1H;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,MAAM,GACb,KAAK,CAAC;IAAE,QAAQ,EAAE,oBAAoB,CAAC;IAAC,WAAW,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAW7E;AAED,eAAO,MAAM,sBAAsB,QAAkC,CAAC"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AA8BvD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,mBAAmB,EAChC,QAAQ,EAAE,oBAAoB,GAC7B,IAAI,CAEN;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,GAAG,oBAAoB,GAAG,SAAS,CAS1H;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,MAAM,GACb,KAAK,CAAC;IAAE,QAAQ,EAAE,oBAAoB,CAAC;IAAC,WAAW,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAW7E;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,QAAkC,CAAC"}

package/dist/metadata.js

@@ -18,9 +18,25 @@ function getOrCreateEventHandlerMap(target) {
   }
   return map;
 }
+
+/**
+ * Define event handler metadata.
+ *
+ * @param target The target.
+ * @param propertyKey The property key.
+ * @param metadata The metadata.
+ */
 export function defineEventHandlerMetadata(target, propertyKey, metadata) {
   getOrCreateEventHandlerMap(target).set(propertyKey, cloneEventHandlerMetadata(metadata));
 }
+
+/**
+ * Get event handler metadata.
+ *
+ * @param target The target.
+ * @param propertyKey The property key.
+ * @returns The get event handler metadata result.
+ */
 export function getEventHandlerMetadata(target, propertyKey) {
   const stored = eventHandlerMetadataStore.get(target)?.get(propertyKey);
   const standard = getStandardEventHandlerMap(target)?.get(propertyKey);
@@ -29,6 +45,13 @@ export function getEventHandlerMetadata(target, propertyKey) {
   }
   return cloneEventHandlerMetadata(stored ?? standard);
 }
+
+/**
+ * Get event handler metadata entries.
+ *
+ * @param target The target.
+ * @returns The get event handler metadata entries result.
+ */
 export function getEventHandlerMetadataEntries(target) {
   const stored = eventHandlerMetadataStore.get(target) ?? new Map();
   const standard = getStandardEventHandlerMap(target) ?? new Map();
@@ -38,4 +61,8 @@ export function getEventHandlerMetadataEntries(target) {
     propertyKey
   })).filter(entry => entry.metadata !== undefined);
 }
+
+/**
+ * Provides the event bus metadata symbol value.
+ */
 export const eventBusMetadataSymbol = standardEventHandlerMetadataKey;

package/dist/status.d.ts

@@ -1,5 +1,11 @@
 import type { PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+/**
+ * Defines the event bus lifecycle state type.
+ */
 export type EventBusLifecycleState = 'created' | 'discovering' | 'ready' | 'stopping' | 'stopped' | 'failed';
+/**
+ * Describes the event bus status adapter input contract.
+ */
 export interface EventBusStatusAdapterInput {
     handlersDiscovered: number;
     lifecycleState: EventBusLifecycleState;
@@ -10,11 +16,20 @@ export interface EventBusStatusAdapterInput {
     transportSubscribeFailures: number;
     waitForHandlersDefault: boolean;
 }
+/**
+ * Describes the event bus platform status snapshot contract.
+ */
 export interface EventBusPlatformStatusSnapshot {
     readiness: PlatformReadinessReport;
     health: PlatformHealthReport;
     ownership: PlatformSnapshot['ownership'];
     details: Record<string, unknown>;
 }
+/**
+ * Create event bus platform status snapshot.
+ *
+ * @param input The input.
+ * @returns The create event bus platform status snapshot result.
+ */
 export declare function createEventBusPlatformStatusSnapshot(input: EventBusStatusAdapterInput): EventBusPlatformStatusSnapshot;
 //# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7G,MAAM,WAAW,0BAA0B;IACzC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,sBAAsB,CAAC;IACvC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,wBAAwB,EAAE,MAAM,CAAC;IACjC,0BAA0B,EAAE,MAAM,CAAC;IACnC,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAwFD,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,0BAA0B,GAAG,8BAA8B,CAqBtH"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7G;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,sBAAsB,CAAC;IACvC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,wBAAwB,EAAE,MAAM,CAAC;IACjC,0BAA0B,EAAE,MAAM,CAAC;IACnC,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAwFD;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,0BAA0B,GAAG,8BAA8B,CAqBtH"}

package/dist/status.js

@@ -1,3 +1,15 @@
+/**
+ * Defines the event bus lifecycle state type.
+ */
+
+/**
+ * Describes the event bus status adapter input contract.
+ */
+
+/**
+ * Describes the event bus platform status snapshot contract.
+ */
+
 function createReadiness(input) {
   if (input.lifecycleState === 'ready' && input.transportSubscribeFailures === 0) {
     return {
@@ -72,6 +84,13 @@ function createHealth(input) {
 function resolveOperationMode(input) {
   return input.transportConfigured ? 'transport-backed' : 'local-only';
 }
+
+/**
+ * Create event bus platform status snapshot.
+ *
+ * @param input The input.
+ * @returns The create event bus platform status snapshot result.
+ */
 export function createEventBusPlatformStatusSnapshot(input) {
   return {
     details: {

package/package.json

@@ -8,7 +8,7 @@
     "pubsub",
     "in-process"
   ],
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -39,9 +39,9 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.2",
-    "@fluojs/di": "^1.0.0-beta.3",
-    "@fluojs/runtime": "^1.0.0-beta.3"
+    "@fluojs/core": "^1.0.0-beta.4",
+    "@fluojs/di": "^1.0.0-beta.6",
+    "@fluojs/runtime": "^1.0.0-beta.11"
   },
   "peerDependencies": {
     "ioredis": "^5.0.0"