@rotorsoft/act 0.12.2 → 0.14.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.
- package/README.md +9 -9
- package/dist/.tsbuildinfo +1 -1
- package/dist/@types/act-builder.d.ts +30 -88
- package/dist/@types/act-builder.d.ts.map +1 -1
- package/dist/@types/act.d.ts +5 -5
- package/dist/@types/ports.d.ts +1 -1
- package/dist/@types/projection-builder.d.ts +2 -6
- package/dist/@types/projection-builder.d.ts.map +1 -1
- package/dist/@types/slice-builder.d.ts +13 -24
- package/dist/@types/slice-builder.d.ts.map +1 -1
- package/dist/@types/state-builder.d.ts +63 -48
- package/dist/@types/state-builder.d.ts.map +1 -1
- package/dist/@types/types/ports.d.ts +1 -1
- package/dist/index.cjs +108 -109
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +108 -107
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
|
@@ -5,14 +5,16 @@
|
|
|
5
5
|
* Fluent builder for composing event-sourced applications.
|
|
6
6
|
*/
|
|
7
7
|
import { Act } from "./act.js";
|
|
8
|
-
import {
|
|
9
|
-
import {
|
|
8
|
+
import type { Projection } from "./projection-builder.js";
|
|
9
|
+
import type { Slice } from "./slice-builder.js";
|
|
10
10
|
import type { Committed, Dispatcher, EventRegister, ReactionOptions, ReactionResolver, Registry, Schema, SchemaRegister, Schemas, Snapshot, State } from "./types/index.js";
|
|
11
11
|
/**
|
|
12
12
|
* Fluent builder interface for composing event-sourced applications.
|
|
13
13
|
*
|
|
14
14
|
* Provides a chainable API for:
|
|
15
|
-
* - Registering states
|
|
15
|
+
* - Registering states via `.withState()`
|
|
16
|
+
* - Registering slices via `.withSlice()`
|
|
17
|
+
* - Registering projections via `.withProjection()`
|
|
16
18
|
* - Defining event reactions via `.on()` → `.do()` → `.to()` or `.void()`
|
|
17
19
|
* - Building the orchestrator via `.build()`
|
|
18
20
|
*
|
|
@@ -25,31 +27,35 @@ import type { Committed, Dispatcher, EventRegister, ReactionOptions, ReactionRes
|
|
|
25
27
|
*/
|
|
26
28
|
export type ActBuilder<S extends SchemaRegister<A>, E extends Schemas, A extends Schemas, M extends Record<string, Schema> = {}> = {
|
|
27
29
|
/**
|
|
28
|
-
* Registers a state definition
|
|
30
|
+
* Registers a state definition with the builder.
|
|
29
31
|
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
* State names, action names, and event names must be unique across the application
|
|
33
|
-
* (partial states with the same name are merged automatically).
|
|
32
|
+
* State names, action names, and event names must be unique across the
|
|
33
|
+
* application (partial states with the same name are merged automatically).
|
|
34
34
|
*
|
|
35
35
|
* @throws {Error} If duplicate action or event names are detected
|
|
36
|
-
*
|
|
37
|
-
* @example Register a state
|
|
38
|
-
* ```typescript
|
|
39
|
-
* const app = act().with(Counter).build();
|
|
40
|
-
* ```
|
|
41
|
-
*
|
|
42
|
-
* @example Register a slice
|
|
43
|
-
* ```typescript
|
|
44
|
-
* const CounterSlice = slice().with(Counter).on("Incremented").do(log).void().build();
|
|
45
|
-
* const app = act().with(CounterSlice).build();
|
|
46
|
-
* ```
|
|
47
36
|
*/
|
|
48
|
-
|
|
37
|
+
withState: <SX extends Schema, EX extends Schemas, AX extends Schemas, NX extends string = string>(state: State<SX, EX, AX, NX>) => ActBuilder<S & {
|
|
49
38
|
[K in keyof AX]: SX;
|
|
50
39
|
}, E & EX, A & AX, M & {
|
|
51
40
|
[K in NX]: SX;
|
|
52
|
-
}
|
|
41
|
+
}>;
|
|
42
|
+
/**
|
|
43
|
+
* Registers a slice with the builder.
|
|
44
|
+
*
|
|
45
|
+
* Merges all the slice's states and reactions into the application.
|
|
46
|
+
* State names, action names, and event names must be unique across the
|
|
47
|
+
* application (partial states with the same name are merged automatically).
|
|
48
|
+
*
|
|
49
|
+
* @throws {Error} If duplicate action or event names are detected
|
|
50
|
+
*/
|
|
51
|
+
withSlice: <SX extends SchemaRegister<AX>, EX extends Schemas, AX extends Schemas, MX extends Record<string, Schema>>(slice: Slice<SX, EX, AX, MX>) => ActBuilder<S & SX, E & EX, A & AX, M & MX>;
|
|
52
|
+
/**
|
|
53
|
+
* Registers a standalone projection with the builder.
|
|
54
|
+
*
|
|
55
|
+
* The projection's events must be a subset of events already registered
|
|
56
|
+
* via `.withState()` or `.withSlice()`.
|
|
57
|
+
*/
|
|
58
|
+
withProjection: <EX extends Schemas>(projection: [Exclude<keyof EX, keyof E>] extends [never] ? Projection<EX> : never) => ActBuilder<S, E, A, M>;
|
|
53
59
|
/**
|
|
54
60
|
* Begins defining a reaction to a specific event.
|
|
55
61
|
*
|
|
@@ -60,47 +66,10 @@ export type ActBuilder<S extends SchemaRegister<A>, E extends Schemas, A extends
|
|
|
60
66
|
* @template K - Event name (must be a registered event)
|
|
61
67
|
* @param event - The event name to react to
|
|
62
68
|
* @returns An object with `.do()` method to define the reaction handler
|
|
63
|
-
*
|
|
64
|
-
* @example
|
|
65
|
-
* ```typescript
|
|
66
|
-
* const app = act()
|
|
67
|
-
* .with(User)
|
|
68
|
-
* .on("UserCreated") // React to UserCreated events
|
|
69
|
-
* .do(async (event) => {
|
|
70
|
-
* await sendWelcomeEmail(event.data.email);
|
|
71
|
-
* })
|
|
72
|
-
* .void()
|
|
73
|
-
* .build();
|
|
74
|
-
* ```
|
|
75
69
|
*/
|
|
76
70
|
on: <K extends keyof E>(event: K) => {
|
|
77
|
-
/**
|
|
78
|
-
* Defines the reaction handler function for the event.
|
|
79
|
-
*
|
|
80
|
-
* The handler receives the committed event and can:
|
|
81
|
-
* - Perform side effects (send emails, call APIs, etc.)
|
|
82
|
-
* - Return an action tuple `[actionName, payload]` to trigger another action
|
|
83
|
-
* - Return `void` or `undefined` for side-effect-only reactions
|
|
84
|
-
*
|
|
85
|
-
* @param handler - The reaction handler function
|
|
86
|
-
* @param options - Optional reaction configuration
|
|
87
|
-
* @param options.blockOnError - Block this stream if handler fails (default: true)
|
|
88
|
-
* @param options.maxRetries - Maximum retry attempts on failure (default: 3)
|
|
89
|
-
* @returns The builder with `.to()` and `.void()` methods for routing configuration
|
|
90
|
-
*/
|
|
91
71
|
do: (handler: (event: Committed<E, K>, stream: string, app: Dispatcher<A>) => Promise<Snapshot<Schema, E> | void>, options?: Partial<ReactionOptions>) => ActBuilder<S, E, A, M> & {
|
|
92
|
-
/**
|
|
93
|
-
* Routes the reaction to a specific target stream.
|
|
94
|
-
*
|
|
95
|
-
* @param resolver - Target stream name (string) or resolver function
|
|
96
|
-
* @returns The builder for chaining
|
|
97
|
-
*/
|
|
98
72
|
to: (resolver: ReactionResolver<E, K> | string) => ActBuilder<S, E, A, M>;
|
|
99
|
-
/**
|
|
100
|
-
* Marks the reaction as void (side-effect only, no target stream).
|
|
101
|
-
*
|
|
102
|
-
* @returns The builder for chaining
|
|
103
|
-
*/
|
|
104
73
|
void: () => ActBuilder<S, E, A, M>;
|
|
105
74
|
};
|
|
106
75
|
};
|
|
@@ -121,51 +90,24 @@ export type ActBuilder<S extends SchemaRegister<A>, E extends Schemas, A extends
|
|
|
121
90
|
/**
|
|
122
91
|
* Creates a new Act orchestrator builder for composing event-sourced applications.
|
|
123
92
|
*
|
|
124
|
-
* The Act orchestrator is responsible for:
|
|
125
|
-
* - Managing state instances (aggregates)
|
|
126
|
-
* - Executing actions and committing events
|
|
127
|
-
* - Processing reactions (event handlers)
|
|
128
|
-
* - Coordinating event-driven workflows
|
|
129
|
-
*
|
|
130
|
-
* Use the fluent API to register states or slices with `.with()`, define event
|
|
131
|
-
* reactions with `.on()`, and build the orchestrator with `.build()`.
|
|
132
|
-
*
|
|
133
|
-
* @template S - State schema register type
|
|
134
|
-
* @template E - Event schemas type
|
|
135
|
-
* @template A - Action schemas type
|
|
136
|
-
* @returns An ActBuilder instance for fluent API configuration
|
|
137
|
-
*
|
|
138
93
|
* @example Basic application with single state
|
|
139
94
|
* ```typescript
|
|
140
|
-
* import { act, state } from "@rotorsoft/act";
|
|
141
|
-
* import { z } from "zod";
|
|
142
|
-
*
|
|
143
|
-
* const Counter = state({ Counter: z.object({ count: z.number() }) })
|
|
144
|
-
* .init(() => ({ count: 0 }))
|
|
145
|
-
* .emits({ Incremented: z.object({ amount: z.number() }) })
|
|
146
|
-
* .patch({ Incremented: (event, state) => ({ count: state.count + event.data.amount }) })
|
|
147
|
-
* .on({ increment: z.object({ by: z.number() }) })
|
|
148
|
-
* .emit((action) => ["Incremented", { amount: action.by }])
|
|
149
|
-
* .build();
|
|
150
|
-
*
|
|
151
95
|
* const app = act()
|
|
152
|
-
* .
|
|
96
|
+
* .withState(Counter)
|
|
153
97
|
* .build();
|
|
154
98
|
* ```
|
|
155
99
|
*
|
|
156
100
|
* @example Application with slices (vertical slice architecture)
|
|
157
101
|
* ```typescript
|
|
158
|
-
* import { act, slice, state } from "@rotorsoft/act";
|
|
159
|
-
*
|
|
160
102
|
* const CounterSlice = slice()
|
|
161
|
-
* .
|
|
103
|
+
* .withState(Counter)
|
|
162
104
|
* .on("Incremented")
|
|
163
105
|
* .do(async (event) => { console.log("incremented!"); })
|
|
164
106
|
* .void()
|
|
165
107
|
* .build();
|
|
166
108
|
*
|
|
167
109
|
* const app = act()
|
|
168
|
-
* .
|
|
110
|
+
* .withSlice(CounterSlice)
|
|
169
111
|
* .build();
|
|
170
112
|
* ```
|
|
171
113
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"act-builder.d.ts","sourceRoot":"","sources":["../../src/act-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,OAAO,
|
|
1
|
+
{"version":3,"file":"act-builder.d.ts","sourceRoot":"","sources":["../../src/act-builder.ts"],"names":[],"mappings":"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"}
|
package/dist/@types/act.d.ts
CHANGED
|
@@ -132,8 +132,8 @@ export declare class Act<S extends SchemaRegister<A>, E extends Schemas, A exten
|
|
|
132
132
|
* @example Reaction triggering another action
|
|
133
133
|
* ```typescript
|
|
134
134
|
* const app = act()
|
|
135
|
-
* .
|
|
136
|
-
* .
|
|
135
|
+
* .withState(Order)
|
|
136
|
+
* .withState(Inventory)
|
|
137
137
|
* .on("OrderPlaced")
|
|
138
138
|
* .do(async (event, context) => {
|
|
139
139
|
* // This action is triggered by an event
|
|
@@ -165,7 +165,7 @@ export declare class Act<S extends SchemaRegister<A>, E extends Schemas, A exten
|
|
|
165
165
|
*
|
|
166
166
|
* Accepts either a State definition object or a state name string. When
|
|
167
167
|
* using a string, the merged state (from partial states registered via
|
|
168
|
-
* `.
|
|
168
|
+
* `.withState()`) is resolved by name.
|
|
169
169
|
*
|
|
170
170
|
* @template SX - State schema type
|
|
171
171
|
* @template EX - Event schemas type
|
|
@@ -389,8 +389,8 @@ export declare class Act<S extends SchemaRegister<A>, E extends Schemas, A exten
|
|
|
389
389
|
* @example Dynamic stream creation
|
|
390
390
|
* ```typescript
|
|
391
391
|
* const app = act()
|
|
392
|
-
* .
|
|
393
|
-
* .
|
|
392
|
+
* .withState(User)
|
|
393
|
+
* .withState(UserStats)
|
|
394
394
|
* .on("UserLoggedIn")
|
|
395
395
|
* .do(async (event) => ["incrementLoginCount", {}])
|
|
396
396
|
* .to((event) => ({
|
package/dist/@types/ports.d.ts
CHANGED
|
@@ -12,7 +12,7 @@ import type { ZodType } from "zod";
|
|
|
12
12
|
import type { Committed, EventRegister, ReactionResolver, Schema, Schemas } from "./types/index.js";
|
|
13
13
|
/**
|
|
14
14
|
* A self-contained projection grouping read-model update handlers.
|
|
15
|
-
* Projections are composed into an Act orchestrator via `act().
|
|
15
|
+
* Projections are composed into an Act orchestrator via `act().withProjection(projection)`.
|
|
16
16
|
*
|
|
17
17
|
* @template E - Event schemas handled by this projection
|
|
18
18
|
*/
|
|
@@ -20,10 +20,6 @@ export type Projection<E extends Schemas> = {
|
|
|
20
20
|
readonly _tag: "Projection";
|
|
21
21
|
readonly events: EventRegister<E>;
|
|
22
22
|
};
|
|
23
|
-
/**
|
|
24
|
-
* Type guard for distinguishing Projection from State and Slice objects.
|
|
25
|
-
*/
|
|
26
|
-
export declare function isProjection(x: any): x is Projection<any>;
|
|
27
23
|
/** Helper: a single-key record mapping an event name to its Zod schema. */
|
|
28
24
|
type EventEntry<K extends string = string, D extends Schema = Schema> = {
|
|
29
25
|
[P in K]: ZodType<D>;
|
|
@@ -45,7 +41,7 @@ type DoResult<E extends Schemas, K extends string, D extends Schema> = Projectio
|
|
|
45
41
|
* Fluent builder interface for composing projections.
|
|
46
42
|
*
|
|
47
43
|
* Provides a chainable API for registering event handlers that update
|
|
48
|
-
* read models. Unlike slices, projections have no `.
|
|
44
|
+
* read models. Unlike slices, projections have no `.withState()` for states
|
|
49
45
|
* and handlers do not receive a `Dispatcher`.
|
|
50
46
|
*
|
|
51
47
|
* When a default target is provided via `projection("target")`, all
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"projection-builder.d.ts","sourceRoot":"","sources":["../../src/projection-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EAGb,gBAAgB,EAChB,MAAM,EACN,OAAO,EACR,MAAM,kBAAkB,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,OAAO,IAAI;IAC1C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CACnC,CAAC;AAEF
|
|
1
|
+
{"version":3,"file":"projection-builder.d.ts","sourceRoot":"","sources":["../../src/projection-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EAGb,gBAAgB,EAChB,MAAM,EACN,OAAO,EACR,MAAM,kBAAkB,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,OAAO,IAAI;IAC1C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CACnC,CAAC;AAEF,2EAA2E;AAC3E,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;KACrE,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CACrB,CAAC;AAEF,iEAAiE;AACjE,KAAK,QAAQ,CACX,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,MAAM,IACd,iBAAiB,CAAC,CAAC,GAAG;KAAG,CAAC,IAAI,CAAC,GAAG,CAAC;CAAE,CAAC,GAAG;IAC3C,EAAE,EAAE,CACF,QAAQ,EAAE,gBAAgB,CAAC,CAAC,GAAG;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,EAAE,CAAC,CAAC,GAAG,MAAM,KACxD,iBAAiB,CAAC,CAAC,GAAG;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,iBAAiB,CAAC,CAAC,GAAG;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAC,CAAC;CACpD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,OAAO,IAAI;IACjD;;;;;;OAMG;IACH,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EACrC,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,KACpB;QACH,EAAE,EAAE,CACF,OAAO,EAAE,CACP,KAAK,EAAE,SAAS,CAAC,CAAC,GAAG;aAAG,CAAC,IAAI,CAAC,GAAG,CAAC;SAAE,EAAE,CAAC,CAAC,EACxC,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,IAAI,CAAC,KACf,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;KACxB,CAAC;IACF;;OAEG;IACH,KAAK,EAAE,MAAM,UAAU,CAAC,CAAC,CAAC,CAAC;IAC3B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CACnC,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,OAAO,GAAG,EAAE,EAC/C,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,GAAE,aAAa,CAAC,CAAC,CAA0B,GAChD,iBAAiB,CAAC,CAAC,CAAC,CAyEtB"}
|
|
@@ -3,7 +3,7 @@ import type { Committed, Dispatcher, EventRegister, ReactionOptions, ReactionRes
|
|
|
3
3
|
/**
|
|
4
4
|
* A self-contained functional slice grouping partial states with their
|
|
5
5
|
* scoped reactions. Slices are composed into an Act orchestrator via
|
|
6
|
-
* `act().
|
|
6
|
+
* `act().withSlice(slice)`.
|
|
7
7
|
*
|
|
8
8
|
* @template S - Schema register for states
|
|
9
9
|
* @template E - Event schemas from this slice's states
|
|
@@ -20,17 +20,11 @@ export type Slice<S extends SchemaRegister<A>, E extends Schemas, A extends Sche
|
|
|
20
20
|
/** @internal phantom field for type-level state name tracking */
|
|
21
21
|
readonly _M?: M;
|
|
22
22
|
};
|
|
23
|
-
/**
|
|
24
|
-
* Type guard for distinguishing Slice from State objects.
|
|
25
|
-
*/
|
|
26
|
-
export declare function isSlice(x: any): x is Slice<any, any, any, any>;
|
|
27
23
|
/**
|
|
28
24
|
* Fluent builder interface for composing functional slices.
|
|
29
25
|
*
|
|
30
|
-
* Provides a chainable API for registering states and
|
|
31
|
-
* scoped to the slice's own events.
|
|
32
|
-
* handlers need via `.with()` — the `app` parameter in `.do()` handlers
|
|
33
|
-
* is typed with every action registered in the slice.
|
|
26
|
+
* Provides a chainable API for registering states and projections,
|
|
27
|
+
* and defining reactions scoped to the slice's own events.
|
|
34
28
|
*
|
|
35
29
|
* @template S - Schema register for states
|
|
36
30
|
* @template E - Event schemas
|
|
@@ -39,25 +33,24 @@ export declare function isSlice(x: any): x is Slice<any, any, any, any>;
|
|
|
39
33
|
*/
|
|
40
34
|
export type SliceBuilder<S extends SchemaRegister<A>, E extends Schemas, A extends Schemas, M extends Record<string, Schema> = {}> = {
|
|
41
35
|
/**
|
|
42
|
-
* Registers a
|
|
36
|
+
* Registers a state definition with the slice.
|
|
43
37
|
*
|
|
44
38
|
* Include every state whose actions your reaction handlers need to
|
|
45
39
|
* dispatch. Duplicate registrations (same state in multiple slices)
|
|
46
40
|
* are handled automatically at composition time.
|
|
47
41
|
*/
|
|
48
|
-
|
|
42
|
+
withState: <SX extends Schema, EX extends Schemas, AX extends Schemas, NX extends string = string>(state: State<SX, EX, AX, NX>) => SliceBuilder<S & {
|
|
49
43
|
[K in keyof AX]: SX;
|
|
50
44
|
}, E & EX, A & AX, M & {
|
|
51
45
|
[K in NX]: SX;
|
|
52
46
|
}>;
|
|
53
47
|
/**
|
|
54
|
-
* Embeds a built Projection within this slice
|
|
55
|
-
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
* and do not receive a Dispatcher.
|
|
48
|
+
* Embeds a built Projection within this slice. The projection's events
|
|
49
|
+
* must be a subset of events from states already registered via
|
|
50
|
+
* `.withState()`. Projection handlers preserve their `(event, stream)`
|
|
51
|
+
* signature and do not receive a Dispatcher.
|
|
59
52
|
*/
|
|
60
|
-
|
|
53
|
+
withProjection: <EP extends Schemas>(projection: [Exclude<keyof EP, keyof E>] extends [never] ? Projection<EP> : never) => SliceBuilder<S, E, A, M>;
|
|
61
54
|
/**
|
|
62
55
|
* Begins defining a reaction scoped to this slice's events.
|
|
63
56
|
*/
|
|
@@ -83,14 +76,10 @@ export type SliceBuilder<S extends SchemaRegister<A>, E extends Schemas, A exten
|
|
|
83
76
|
* reactions into self-contained feature modules. Reactions defined in a slice
|
|
84
77
|
* are type-scoped to events from that slice's states only.
|
|
85
78
|
*
|
|
86
|
-
* Include all states whose actions your handlers dispatch via `.with()`.
|
|
87
|
-
* When multiple slices share the same state, duplicates are merged
|
|
88
|
-
* automatically at `act().with(slice)` composition time.
|
|
89
|
-
*
|
|
90
79
|
* @example Single-state slice with typed dispatch
|
|
91
80
|
* ```typescript
|
|
92
81
|
* const CounterSlice = slice()
|
|
93
|
-
* .
|
|
82
|
+
* .withState(Counter)
|
|
94
83
|
* .on("Incremented")
|
|
95
84
|
* .do(async (event, _stream, app) => {
|
|
96
85
|
* await app.do("reset", target, {});
|
|
@@ -102,8 +91,8 @@ export type SliceBuilder<S extends SchemaRegister<A>, E extends Schemas, A exten
|
|
|
102
91
|
* @example Cross-state dispatch (include both states)
|
|
103
92
|
* ```typescript
|
|
104
93
|
* const CreationSlice = slice()
|
|
105
|
-
* .
|
|
106
|
-
* .
|
|
94
|
+
* .withState(TicketCreation)
|
|
95
|
+
* .withState(TicketOperations) // handler can dispatch AssignTicket
|
|
107
96
|
* .on("TicketOpened").do(async (event, _stream, app) => {
|
|
108
97
|
* await app.do("AssignTicket", target, payload, event);
|
|
109
98
|
* })
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"slice-builder.d.ts","sourceRoot":"","sources":["../../src/slice-builder.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,aAAa,EAGb,eAAe,EACf,gBAAgB,EAChB,MAAM,EACN,cAAc,EACd,OAAO,EACP,QAAQ,EACR,KAAK,EACN,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;GASG;AACH,MAAM,MAAM,KAAK,CACf,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,EAC3B,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,EAEjB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,IACnC;IACF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,mEAAmE;IACnE,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAChB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;CACjB,CAAC;AAEF
|
|
1
|
+
{"version":3,"file":"slice-builder.d.ts","sourceRoot":"","sources":["../../src/slice-builder.ts"],"names":[],"mappings":"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"}
|
|
@@ -46,7 +46,7 @@ export type StateBuilder<S extends Schema, N extends string = string> = {
|
|
|
46
46
|
*
|
|
47
47
|
* @template E - Event schemas type
|
|
48
48
|
* @param events - Object mapping event names to Zod schemas
|
|
49
|
-
* @returns
|
|
49
|
+
* @returns An ActionBuilder (with optional `.patch()` to override specific reducers)
|
|
50
50
|
*
|
|
51
51
|
* @example
|
|
52
52
|
* ```typescript
|
|
@@ -57,27 +57,28 @@ export type StateBuilder<S extends Schema, N extends string = string> = {
|
|
|
57
57
|
* })
|
|
58
58
|
* ```
|
|
59
59
|
*/
|
|
60
|
-
emits: <E extends Schemas>(events: ZodTypes<E>) => {
|
|
60
|
+
emits: <E extends Schemas>(events: ZodTypes<E>) => ActionBuilder<S, E, {}, N> & {
|
|
61
61
|
/**
|
|
62
|
-
*
|
|
62
|
+
* Overrides specific event reducers. Events without a custom patch
|
|
63
|
+
* default to passthrough: `({ data }) => data` (event data merges
|
|
64
|
+
* into state).
|
|
63
65
|
*
|
|
64
|
-
*
|
|
65
|
-
* and return the changes to apply. Return partial state objects; unchanged fields
|
|
66
|
-
* are preserved automatically.
|
|
67
|
-
*
|
|
68
|
-
* @param patch - Object mapping event names to patch handler functions
|
|
66
|
+
* @param patch - Partial map of event names to patch handler functions
|
|
69
67
|
* @returns An ActionBuilder for defining actions
|
|
70
68
|
*
|
|
71
|
-
* @example
|
|
69
|
+
* @example Only override the events that need custom logic
|
|
72
70
|
* ```typescript
|
|
71
|
+
* .emits({ TicketOpened, TicketClosed, TicketResolved })
|
|
73
72
|
* .patch({
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
73
|
+
* TicketOpened: ({ data }) => {
|
|
74
|
+
* const { message, messageId, userId, ...other } = data;
|
|
75
|
+
* return { ...other, userId, messages: { [messageId]: { ... } } };
|
|
76
|
+
* },
|
|
77
77
|
* })
|
|
78
|
+
* // TicketClosed and TicketResolved use passthrough
|
|
78
79
|
* ```
|
|
79
80
|
*/
|
|
80
|
-
patch: (patch: PatchHandlers<S, E
|
|
81
|
+
patch: (patch: Partial<PatchHandlers<S, E>>) => ActionBuilder<S, E, {}, N>;
|
|
81
82
|
};
|
|
82
83
|
};
|
|
83
84
|
};
|
|
@@ -168,20 +169,28 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
|
|
|
168
169
|
* and must return one or more events to emit. Events are applied to state
|
|
169
170
|
* via the patch handlers defined earlier.
|
|
170
171
|
*
|
|
171
|
-
*
|
|
172
|
+
* Pass a string event name for passthrough: the action payload becomes
|
|
173
|
+
* the event data directly.
|
|
174
|
+
*
|
|
175
|
+
* @param handler - Function that returns events to emit, or event name string for passthrough
|
|
172
176
|
* @returns The ActionBuilder for chaining more actions
|
|
173
177
|
*
|
|
174
|
-
* @example
|
|
178
|
+
* @example Custom handler
|
|
175
179
|
* ```typescript
|
|
176
180
|
* .emit((action, snapshot) => {
|
|
177
181
|
* const newBalance = snapshot.state.balance + action.amount;
|
|
178
182
|
* return ["Deposited", { amount: action.amount, newBalance }];
|
|
179
183
|
* })
|
|
180
184
|
* ```
|
|
185
|
+
*
|
|
186
|
+
* @example Passthrough (action payload = event data)
|
|
187
|
+
* ```typescript
|
|
188
|
+
* .emit("TicketAssigned")
|
|
189
|
+
* ```
|
|
181
190
|
*/
|
|
182
191
|
emit: (handler: ActionHandler<S, E, {
|
|
183
192
|
[P in K]: AX;
|
|
184
|
-
}, K>) => ActionBuilder<S, E, A & {
|
|
193
|
+
}, K> | (keyof E & string)) => ActionBuilder<S, E, A & {
|
|
185
194
|
[P in K]: AX;
|
|
186
195
|
}, N>;
|
|
187
196
|
};
|
|
@@ -192,9 +201,17 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
|
|
|
192
201
|
* and must return one or more events to emit. Return a single event as
|
|
193
202
|
* `["EventName", data]` or multiple events as an array of event tuples.
|
|
194
203
|
*
|
|
195
|
-
*
|
|
204
|
+
* Pass a string event name for passthrough: the action payload becomes
|
|
205
|
+
* the event data directly.
|
|
206
|
+
*
|
|
207
|
+
* @param handler - Function that returns events to emit, or event name string for passthrough
|
|
196
208
|
* @returns The ActionBuilder for chaining more actions
|
|
197
209
|
*
|
|
210
|
+
* @example Passthrough (action payload = event data)
|
|
211
|
+
* ```typescript
|
|
212
|
+
* .emit("Incremented")
|
|
213
|
+
* ```
|
|
214
|
+
*
|
|
198
215
|
* @example Single event
|
|
199
216
|
* ```typescript
|
|
200
217
|
* .emit((action) => ["Incremented", { amount: action.by }])
|
|
@@ -207,23 +224,10 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
|
|
|
207
224
|
* ["LogUpdated", { message: `Incremented by ${action.by}` }]
|
|
208
225
|
* ])
|
|
209
226
|
* ```
|
|
210
|
-
*
|
|
211
|
-
* @example Conditional events
|
|
212
|
-
* ```typescript
|
|
213
|
-
* .emit((action, snapshot) => {
|
|
214
|
-
* if (snapshot.state.count + action.by >= 100) {
|
|
215
|
-
* return [
|
|
216
|
-
* ["Incremented", { amount: action.by }],
|
|
217
|
-
* ["MilestoneReached", { milestone: 100 }]
|
|
218
|
-
* ];
|
|
219
|
-
* }
|
|
220
|
-
* return ["Incremented", { amount: action.by }];
|
|
221
|
-
* })
|
|
222
|
-
* ```
|
|
223
227
|
*/
|
|
224
228
|
emit: (handler: ActionHandler<S, E, {
|
|
225
229
|
[P in K]: AX;
|
|
226
|
-
}, K>) => ActionBuilder<S, E, A & {
|
|
230
|
+
}, K> | (keyof E & string)) => ActionBuilder<S, E, A & {
|
|
227
231
|
[P in K]: AX;
|
|
228
232
|
}, N>;
|
|
229
233
|
};
|
|
@@ -272,7 +276,7 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
|
|
|
272
276
|
* const Counter = state({ Counter: schema })
|
|
273
277
|
* .init(() => ({ count: 0 }))
|
|
274
278
|
* .emits({ Incremented: z.object({ amount: z.number() }) })
|
|
275
|
-
* .patch({ Incremented: (
|
|
279
|
+
* .patch({ Incremented: ({ data }, state) => ({ count: state.count + data.amount }) })
|
|
276
280
|
* .on({ increment: z.object({ by: z.number() }) })
|
|
277
281
|
* .emit((action) => ["Incremented", { amount: action.by }])
|
|
278
282
|
* .build(); // Returns State<S, E, A, N>
|
|
@@ -290,9 +294,9 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
|
|
|
290
294
|
*
|
|
291
295
|
* The state builder provides a fluent API for defining:
|
|
292
296
|
* 1. Initial state via `.init()`
|
|
293
|
-
* 2. Event types via `.emits()`
|
|
294
|
-
* 3.
|
|
295
|
-
* 4. Actions (commands) via `.on()` → `.emit()`
|
|
297
|
+
* 2. Event types via `.emits()` — all events default to passthrough (`({ data }) => data`)
|
|
298
|
+
* 3. Custom event reducers via `.patch()` (optional — only for events that need custom logic)
|
|
299
|
+
* 4. Actions (commands) via `.on()` → `.emit()` — pass an event name string for passthrough
|
|
296
300
|
* 5. Business rules (invariants) via `.given()`
|
|
297
301
|
* 6. Snapshotting strategy via `.snap()`
|
|
298
302
|
*
|
|
@@ -300,7 +304,7 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
|
|
|
300
304
|
* @param entry - Single-key record mapping state name to Zod schema (e.g., `{ Counter: z.object({ count: z.number() }) }`)
|
|
301
305
|
* @returns A StateBuilder instance for fluent API configuration
|
|
302
306
|
*
|
|
303
|
-
* @example Basic counter state
|
|
307
|
+
* @example Basic counter state (with custom patch)
|
|
304
308
|
* ```typescript
|
|
305
309
|
* import { state } from "@rotorsoft/act";
|
|
306
310
|
* import { z } from "zod";
|
|
@@ -310,14 +314,25 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
|
|
|
310
314
|
* .emits({
|
|
311
315
|
* Incremented: z.object({ amount: z.number() })
|
|
312
316
|
* })
|
|
313
|
-
* .patch({
|
|
314
|
-
* Incremented: (
|
|
317
|
+
* .patch({ // optional — only for events needing custom reducers
|
|
318
|
+
* Incremented: ({ data }, state) => ({ count: state.count + data.amount })
|
|
315
319
|
* })
|
|
316
320
|
* .on({ increment: z.object({ by: z.number() }) })
|
|
317
321
|
* .emit((action) => ["Incremented", { amount: action.by }])
|
|
318
322
|
* .build();
|
|
319
323
|
* ```
|
|
320
324
|
*
|
|
325
|
+
* @example Passthrough state (no custom patch or emit needed)
|
|
326
|
+
* ```typescript
|
|
327
|
+
* const DigitBoard = state({ DigitBoard: z.object({ digit: z.string() }) })
|
|
328
|
+
* .init(() => ({ digit: "" }))
|
|
329
|
+
* .emits({ DigitCounted: z.object({ digit: z.string() }) })
|
|
330
|
+
* // no .patch() — passthrough is the default (event data merges into state)
|
|
331
|
+
* .on({ CountDigit: z.object({ digit: z.string() }) })
|
|
332
|
+
* .emit("DigitCounted") // string passthrough — action payload becomes event data
|
|
333
|
+
* .build();
|
|
334
|
+
* ```
|
|
335
|
+
*
|
|
321
336
|
* @example State with multiple events and invariants
|
|
322
337
|
* ```typescript
|
|
323
338
|
* const BankAccount = state({ BankAccount: z.object({
|
|
@@ -331,29 +346,29 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
|
|
|
331
346
|
* Withdrawn: z.object({ amount: z.number() }),
|
|
332
347
|
* Closed: z.object({})
|
|
333
348
|
* })
|
|
334
|
-
* .patch({
|
|
335
|
-
* Deposited: (
|
|
336
|
-
* Withdrawn: (
|
|
349
|
+
* .patch({ // only override events needing custom logic
|
|
350
|
+
* Deposited: ({ data }, state) => ({ balance: state.balance + data.amount }),
|
|
351
|
+
* Withdrawn: ({ data }, state) => ({ balance: state.balance - data.amount }),
|
|
337
352
|
* Closed: () => ({ status: "closed", balance: 0 })
|
|
338
353
|
* })
|
|
339
354
|
* .on({ deposit: z.object({ amount: z.number() }) })
|
|
340
355
|
* .given([
|
|
341
356
|
* (_, snap) => snap.state.status === "open" || "Account must be open"
|
|
342
357
|
* ])
|
|
343
|
-
* .emit(
|
|
358
|
+
* .emit("Deposited") // passthrough — action payload { amount } becomes event data
|
|
344
359
|
* .on({ withdraw: z.object({ amount: z.number() }) })
|
|
345
360
|
* .given([
|
|
346
361
|
* (_, snap) => snap.state.status === "open" || "Account must be open",
|
|
347
362
|
* (_, snap, action) =>
|
|
348
363
|
* snap.state.balance >= action.amount || "Insufficient funds"
|
|
349
364
|
* ])
|
|
350
|
-
* .emit(
|
|
365
|
+
* .emit("Withdrawn")
|
|
351
366
|
* .on({ close: z.object({}) })
|
|
352
367
|
* .given([
|
|
353
368
|
* (_, snap) => snap.state.status === "open" || "Already closed",
|
|
354
369
|
* (_, snap) => snap.state.balance === 0 || "Balance must be zero"
|
|
355
370
|
* ])
|
|
356
|
-
* .emit(
|
|
371
|
+
* .emit("Closed")
|
|
357
372
|
* .build();
|
|
358
373
|
* ```
|
|
359
374
|
*
|
|
@@ -369,14 +384,14 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
|
|
|
369
384
|
* UserCreated: z.object({ name: z.string(), email: z.string() }),
|
|
370
385
|
* UserLoggedIn: z.object({})
|
|
371
386
|
* })
|
|
372
|
-
* .patch({
|
|
373
|
-
* UserCreated: (event) => event.data,
|
|
387
|
+
* .patch({ // only override events needing custom logic
|
|
374
388
|
* UserLoggedIn: (_, state) => ({ loginCount: state.loginCount + 1 })
|
|
375
389
|
* })
|
|
390
|
+
* // UserCreated uses passthrough — event data merges into state
|
|
376
391
|
* .on({ createUser: z.object({ name: z.string(), email: z.string() }) })
|
|
377
|
-
* .emit(
|
|
392
|
+
* .emit("UserCreated") // passthrough
|
|
378
393
|
* .on({ login: z.object({}) })
|
|
379
|
-
* .emit(
|
|
394
|
+
* .emit("UserLoggedIn")
|
|
380
395
|
* .snap((snap) => snap.patches >= 10) // Snapshot every 10 events
|
|
381
396
|
* .build();
|
|
382
397
|
* ```
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"state-builder.d.ts","sourceRoot":"","sources":["../../src/state-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAC9B,OAAO,EACL,aAAa,EAGb,SAAS,EACT,aAAa,EACb,MAAM,EACN,OAAO,EACP,QAAQ,EACR,KAAK,EACL,QAAQ,EACT,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACtE;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAK;QACjC;;;;;;;;;;;;;;;;;;WAkBG;QACH,KAAK,EAAE,CAAC,CAAC,SAAS,OAAO,EACvB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,
|
|
1
|
+
{"version":3,"file":"state-builder.d.ts","sourceRoot":"","sources":["../../src/state-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAC9B,OAAO,EACL,aAAa,EAGb,SAAS,EACT,aAAa,EACb,MAAM,EACN,OAAO,EACP,QAAQ,EACR,KAAK,EACL,QAAQ,EACT,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACtE;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAK;QACjC;;;;;;;;;;;;;;;;;;WAkBG;QACH,KAAK,EAAE,CAAC,CAAC,SAAS,OAAO,EACvB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,KAEhB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG;YAChC;;;;;;;;;;;;;;;;;;;eAmBG;YACH,KAAK,EAAE,CACL,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAEhC,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;SACjC,CAAC;KACH,CAAC;CACH,CAAC;AAEF,0EAA0E;AAC1E,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;KACrE,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CACrB,CAAC;AAEF,4EAA4E;AAC5E,KAAK,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI;KACvE,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,CACvB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,MAAM,GAAG,MAAM,IACvB;IACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM,EACtC,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,EAAE,CAAC,KACtB;QACH;;;;;;;;;;;;;;;;;WAiBG;QACH,KAAK,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK;YAChC;;;;;;;;;;;;;;;;;;;;;;;;;eAyBG;YACH,IAAI,EAAE,CACJ,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE;iBAAG,CAAC,IAAI,CAAC,GAAG,EAAE;aAAE,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,KACnE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG;iBAAG,CAAC,IAAI,CAAC,GAAG,EAAE;aAAE,EAAE,CAAC,CAAC,CAAC;SACnD,CAAC;QACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA8BG;QACH,IAAI,EAAE,CACJ,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE;aAAG,CAAC,IAAI,CAAC,GAAG,EAAE;SAAE,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,KACnE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG;aAAG,CAAC,IAAI,CAAC,GAAG,EAAE;SAAE,EAAE,CAAC,CAAC,CAAC;KACnD,CAAC;IACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,IAAI,EAAE,CACJ,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO,KACxC,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoHG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EACtD,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACtB,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CA8CpB"}
|