@fluojs/cqrs 1.0.0-beta.1 → 1.0.0-beta.2
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.
- package/README.ko.md +9 -0
- package/README.md +9 -0
- package/dist/types.d.ts +9 -6
- package/dist/types.d.ts.map +1 -1
- package/package.json +4 -4
package/README.ko.md
CHANGED
|
@@ -11,6 +11,7 @@ fluo 애플리케이션을 위한 CQRS 패키지입니다. 부트스트랩 시
|
|
|
11
11
|
- [빠른 시작](#빠른-시작)
|
|
12
12
|
- [공통 패턴](#공통-패턴)
|
|
13
13
|
- [Saga 프로세스 매니저](#saga-프로세스-매니저)
|
|
14
|
+
- [Event 발행 계약](#event-발행-계약)
|
|
14
15
|
- [심볼 토큰](#심볼-토큰)
|
|
15
16
|
- [공개 API 개요](#공개-api-개요)
|
|
16
17
|
- [관련 패키지](#관련-패키지)
|
|
@@ -107,6 +108,14 @@ class UserSaga implements ISaga<UserCreatedEvent> {
|
|
|
107
108
|
|
|
108
109
|
이제 saga 실행은 같은 프로세스 안에서 동일 saga route로 순환 재진입하거나 중첩 hop 수가 32를 넘으면 `SagaTopologyError`로 즉시 실패합니다. 서로 다른 이벤트 단계를 순차 처리하는 multi-stage saga는 계속 허용되지만, in-process saga graph 전체는 비순환(acyclic) 구조를 유지해야 하며, 의도적인 순환/피드백 루프나 더 긴 체인은 외부 transport, scheduler, 또는 다른 bounded boundary 뒤로 이동해야 합니다.
|
|
109
110
|
|
|
111
|
+
### Event 발행 계약
|
|
112
|
+
|
|
113
|
+
`CqrsEventBusService.publish(event)`는 CQRS event pipeline을 고정된 순서로 실행합니다. 먼저 일치하는 `@EventHandler(...)` provider를 실행하고, 그다음 일치하는 `@Saga(...)` provider를 실행한 뒤, 마지막으로 `@fluojs/event-bus`로 위임 발행합니다. `publishAll(events)`는 각 event의 CQRS handler, saga, 위임 발행 호출을 기다린 뒤 다음 event를 발행하므로 입력 순서를 보존합니다. `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })`로 설정한 경우 위임 발행 호출은 일치하는 `@OnEvent(...)` subscriber가 완료되기 전에 resolve될 수 있으므로, 이 모드에서 `publish(...)`와 `publishAll(...)`는 subscriber 완료를 의미하지 않습니다.
|
|
114
|
+
|
|
115
|
+
각 CQRS event handler와 saga는 매칭된 event prototype이 복원된 격리 event 복사본을 받습니다. 이 복사본을 mutate해도 변경은 현재 handler 또는 saga route 안에만 머물며, 다른 CQRS handler, saga, 원본 event 객체, 또는 위임된 `@fluojs/event-bus` subscriber에는 보이지 않습니다. 위임된 event-bus 발행은 CQRS side effect가 끝난 뒤 원본 event를 받으므로, `@OnEvent(...)` projection과 transport는 CQRS handler가 mutate한 복사본이 아니라 호출자가 소유한 payload를 관찰합니다.
|
|
116
|
+
|
|
117
|
+
Event class는 payload state를 clone 가능하고 enumerable하게 유지해야 합니다. 문자열 key와 symbol key를 가진 enumerable payload field는 shared core clone fallback으로 보존되지만, 열린 socket, function, process-local handle처럼 의도적으로 clone할 수 없는 resource는 발행 전에 ID나 다른 serializable boundary로 표현해야 합니다.
|
|
118
|
+
|
|
110
119
|
### 심볼 토큰
|
|
111
120
|
|
|
112
121
|
CQRS 버스에 명시적인 Symbol 토큰이 필요하면 다음 익스포트를 사용할 수 있습니다.
|
package/README.md
CHANGED
|
@@ -11,6 +11,7 @@ CQRS primitives for fluo applications with bootstrap-time handler discovery, com
|
|
|
11
11
|
- [Quick Start](#quick-start)
|
|
12
12
|
- [Common Patterns](#common-patterns)
|
|
13
13
|
- [Saga Process Managers](#saga-process-managers)
|
|
14
|
+
- [Event Publishing Contracts](#event-publishing-contracts)
|
|
14
15
|
- [Symbol Tokens](#symbol-tokens)
|
|
15
16
|
- [Public API Overview](#public-api-overview)
|
|
16
17
|
- [Related Packages](#related-packages)
|
|
@@ -107,6 +108,14 @@ class UserSaga implements ISaga<UserCreatedEvent> {
|
|
|
107
108
|
|
|
108
109
|
Saga execution now fails fast with `SagaTopologyError` when an in-process publish chain re-enters the same saga route cyclically or exceeds 32 nested saga hops. Multi-stage sagas may still react to different event types in sequence, but in-process saga graphs must stay acyclic overall; move intentionally cyclic or long-running feedback loops behind an external transport, scheduler, or other bounded boundary.
|
|
109
110
|
|
|
111
|
+
### Event Publishing Contracts
|
|
112
|
+
|
|
113
|
+
`CqrsEventBusService.publish(event)` runs the CQRS event pipeline in a fixed order: matching `@EventHandler(...)` providers first, matching `@Saga(...)` providers second, and delegated `@fluojs/event-bus` publication last. `publishAll(events)` preserves the input order by awaiting each event's CQRS handlers, sagas, and delegated publication call before publishing the next event. When `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })` is configured, the delegated publication call can resolve before matching `@OnEvent(...)` subscribers finish, so `publish(...)` and `publishAll(...)` do not imply subscriber completion in that mode.
|
|
114
|
+
|
|
115
|
+
Each CQRS event handler and saga receives an isolated event copy with the matched event prototype restored. Mutating that copy is local to the current handler or saga route; those mutations are not visible to other CQRS handlers, sagas, the original event object, or delegated `@fluojs/event-bus` subscribers. The delegated event-bus publication receives the original event after CQRS side effects complete, so `@OnEvent(...)` projections and transports observe the caller-owned payload rather than a CQRS handler's mutated copy.
|
|
116
|
+
|
|
117
|
+
Event classes should keep their payload state cloneable and enumerable. String-keyed and symbol-keyed enumerable payload fields are preserved by the shared core clone fallback, while intentionally non-cloneable resources such as open sockets, functions, or process-local handles should be represented by IDs or other serializable boundaries before publishing.
|
|
118
|
+
|
|
110
119
|
### Symbol Tokens
|
|
111
120
|
|
|
112
121
|
Use these exports when you want explicit symbol tokens for the CQRS buses:
|
package/dist/types.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ export interface ICommand {
|
|
|
6
6
|
export interface IQuery<TResult = unknown> {
|
|
7
7
|
readonly __queryResultType__?: TResult;
|
|
8
8
|
}
|
|
9
|
-
/** Marker interface for events published through the CQRS event bus. */
|
|
9
|
+
/** Marker interface for cloneable domain events published through the CQRS event bus. */
|
|
10
10
|
export interface IEvent {
|
|
11
11
|
}
|
|
12
12
|
/** Contract implemented by classes decorated with {@link CommandHandler}. */
|
|
@@ -32,9 +32,9 @@ export interface IQueryHandler<TQuery extends IQuery<TResult>, TResult = unknown
|
|
|
32
32
|
/** Contract implemented by classes decorated with {@link EventHandler}. */
|
|
33
33
|
export interface IEventHandler<TEvent extends IEvent> {
|
|
34
34
|
/**
|
|
35
|
-
* Reacts to one published event instance.
|
|
35
|
+
* Reacts to one isolated copy of a published event instance.
|
|
36
36
|
*
|
|
37
|
-
* @param event Event payload
|
|
37
|
+
* @param event Event payload cloned for this handler before delegated event-bus publication.
|
|
38
38
|
* @returns A promise or void once side effects complete.
|
|
39
39
|
*/
|
|
40
40
|
handle(event: TEvent): void | Promise<void>;
|
|
@@ -42,9 +42,9 @@ export interface IEventHandler<TEvent extends IEvent> {
|
|
|
42
42
|
/** Contract implemented by classes decorated with {@link Saga}. */
|
|
43
43
|
export interface ISaga<TEvent extends IEvent = IEvent> {
|
|
44
44
|
/**
|
|
45
|
-
* Reacts to one event and typically emits follow-up commands.
|
|
45
|
+
* Reacts to one isolated copy of an event and typically emits follow-up commands.
|
|
46
46
|
*
|
|
47
|
-
* @param event Event payload
|
|
47
|
+
* @param event Event payload cloned for this saga route before delegated event-bus publication.
|
|
48
48
|
* @returns A promise or void once orchestration side effects complete.
|
|
49
49
|
*/
|
|
50
50
|
handle(event: TEvent): void | Promise<void>;
|
|
@@ -144,7 +144,10 @@ export interface QueryBus {
|
|
|
144
144
|
/** Event publishing facade exposed by the CQRS module. */
|
|
145
145
|
export interface CqrsEventBus {
|
|
146
146
|
/**
|
|
147
|
-
* Publishes one event to the underlying event bus.
|
|
147
|
+
* Publishes one event to local CQRS handlers, sagas, and the underlying event bus.
|
|
148
|
+
*
|
|
149
|
+
* Local CQRS handlers and sagas receive isolated event copies. Delegated `@fluojs/event-bus`
|
|
150
|
+
* subscribers receive the original event after local CQRS side effects complete.
|
|
148
151
|
*
|
|
149
152
|
* @param event Event instance to publish.
|
|
150
153
|
* @returns A promise that resolves once publication completes.
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,2EAA2E;AAC3E,MAAM,WAAW,QAAQ;CAAG;AAE5B,mGAAmG;AACnG,MAAM,WAAW,MAAM,CAAC,OAAO,GAAG,OAAO;IACvC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC;AAED,
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
"saga",
|
|
10
10
|
"event-sourcing"
|
|
11
11
|
],
|
|
12
|
-
"version": "1.0.0-beta.
|
|
12
|
+
"version": "1.0.0-beta.2",
|
|
13
13
|
"private": false,
|
|
14
14
|
"license": "MIT",
|
|
15
15
|
"repository": {
|
|
@@ -37,9 +37,9 @@
|
|
|
37
37
|
],
|
|
38
38
|
"dependencies": {
|
|
39
39
|
"@fluojs/core": "^1.0.0-beta.1",
|
|
40
|
-
"@fluojs/di": "^1.0.0-beta.
|
|
41
|
-
"@fluojs/
|
|
42
|
-
"@fluojs/
|
|
40
|
+
"@fluojs/di": "^1.0.0-beta.2",
|
|
41
|
+
"@fluojs/event-bus": "^1.0.0-beta.2",
|
|
42
|
+
"@fluojs/runtime": "^1.0.0-beta.2"
|
|
43
43
|
},
|
|
44
44
|
"devDependencies": {
|
|
45
45
|
"vitest": "^3.2.4"
|