@rotorsoft/act 1.32.29 → 1.33.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 (141) hide show
  1. package/README.md +0 -1
  2. package/dist/.tsbuildinfo +1 -1
  3. package/dist/@types/act.d.ts +41 -233
  4. package/dist/@types/act.d.ts.map +1 -1
  5. package/dist/@types/adapters/in-memory-store.d.ts.map +1 -1
  6. package/dist/@types/builders/act-builder.d.ts +2 -115
  7. package/dist/@types/builders/act-builder.d.ts.map +1 -1
  8. package/dist/@types/builders/builder-utils.d.ts +1 -1
  9. package/dist/@types/builders/builder-utils.d.ts.map +1 -1
  10. package/dist/@types/builders/event-builder.d.ts +5 -5
  11. package/dist/@types/builders/event-builder.d.ts.map +1 -1
  12. package/dist/@types/builders/merge.d.ts +1 -1
  13. package/dist/@types/builders/merge.d.ts.map +1 -1
  14. package/dist/@types/builders/projection-builder.d.ts +2 -144
  15. package/dist/@types/builders/projection-builder.d.ts.map +1 -1
  16. package/dist/@types/builders/slice-builder.d.ts +2 -71
  17. package/dist/@types/builders/slice-builder.d.ts.map +1 -1
  18. package/dist/@types/builders/state-builder.d.ts +2 -376
  19. package/dist/@types/builders/state-builder.d.ts.map +1 -1
  20. package/dist/@types/config.d.ts +6 -43
  21. package/dist/@types/config.d.ts.map +1 -1
  22. package/dist/@types/csv.d.ts +1 -15
  23. package/dist/@types/csv.d.ts.map +1 -1
  24. package/dist/@types/index.d.ts +0 -1
  25. package/dist/@types/index.d.ts.map +1 -1
  26. package/dist/@types/internal/autoclose-policy.d.ts +9 -108
  27. package/dist/@types/internal/autoclose-policy.d.ts.map +1 -1
  28. package/dist/@types/internal/autoclose-reaction.d.ts +1 -9
  29. package/dist/@types/internal/autoclose-reaction.d.ts.map +1 -1
  30. package/dist/@types/internal/autoclose-window.d.ts +2 -15
  31. package/dist/@types/internal/autoclose-window.d.ts.map +1 -1
  32. package/dist/@types/internal/backoff.d.ts +1 -6
  33. package/dist/@types/internal/backoff.d.ts.map +1 -1
  34. package/dist/@types/internal/circuit-breaker.d.ts +1 -4
  35. package/dist/@types/internal/circuit-breaker.d.ts.map +1 -1
  36. package/dist/@types/{builders/build-classify.d.ts → internal/classify.d.ts} +2 -15
  37. package/dist/@types/internal/classify.d.ts.map +1 -0
  38. package/dist/@types/internal/close-cycle.d.ts +0 -13
  39. package/dist/@types/internal/close-cycle.d.ts.map +1 -1
  40. package/dist/@types/internal/config.d.ts +9 -81
  41. package/dist/@types/internal/config.d.ts.map +1 -1
  42. package/dist/@types/internal/correlate-cycle.d.ts +1 -1
  43. package/dist/@types/internal/correlate-cycle.d.ts.map +1 -1
  44. package/dist/@types/internal/{correlator.d.ts → correlation-id.d.ts} +1 -8
  45. package/dist/@types/internal/correlation-id.d.ts.map +1 -0
  46. package/dist/@types/internal/date-reviver.d.ts +0 -5
  47. package/dist/@types/internal/date-reviver.d.ts.map +1 -1
  48. package/dist/@types/internal/defer-config.d.ts +0 -13
  49. package/dist/@types/internal/defer-config.d.ts.map +1 -1
  50. package/dist/@types/internal/defer-timer.d.ts +1 -5
  51. package/dist/@types/internal/defer-timer.d.ts.map +1 -1
  52. package/dist/@types/internal/drain-cycle.d.ts +1 -1
  53. package/dist/@types/internal/drain-cycle.d.ts.map +1 -1
  54. package/dist/@types/internal/{drain.d.ts → drain-ops.d.ts} +1 -7
  55. package/dist/@types/internal/drain-ops.d.ts.map +1 -0
  56. package/dist/@types/internal/drain-ratio.d.ts +0 -5
  57. package/dist/@types/internal/drain-ratio.d.ts.map +1 -1
  58. package/dist/@types/internal/event-sourcing.d.ts +1 -8
  59. package/dist/@types/internal/event-sourcing.d.ts.map +1 -1
  60. package/dist/@types/internal/event-versions.d.ts +0 -9
  61. package/dist/@types/internal/event-versions.d.ts.map +1 -1
  62. package/dist/@types/internal/lru-map.d.ts +0 -9
  63. package/dist/@types/internal/lru-map.d.ts.map +1 -1
  64. package/dist/@types/internal/pii.d.ts +78 -0
  65. package/dist/@types/internal/pii.d.ts.map +1 -0
  66. package/dist/@types/internal/projection-fold.d.ts +1 -5
  67. package/dist/@types/internal/projection-fold.d.ts.map +1 -1
  68. package/dist/@types/internal/{close-signal.d.ts → reaction-dispatch.d.ts} +46 -6
  69. package/dist/@types/internal/reaction-dispatch.d.ts.map +1 -0
  70. package/dist/@types/internal/report-once.d.ts +1 -8
  71. package/dist/@types/internal/report-once.d.ts.map +1 -1
  72. package/dist/@types/internal/settle.d.ts +21 -21
  73. package/dist/@types/internal/settle.d.ts.map +1 -1
  74. package/dist/@types/internal/tracing.d.ts +3 -14
  75. package/dist/@types/internal/tracing.d.ts.map +1 -1
  76. package/dist/@types/internal/walk-streams.d.ts +0 -2
  77. package/dist/@types/internal/walk-streams.d.ts.map +1 -1
  78. package/dist/@types/ports.d.ts +3 -43
  79. package/dist/@types/ports.d.ts.map +1 -1
  80. package/dist/@types/scoped.d.ts +1 -6
  81. package/dist/@types/scoped.d.ts.map +1 -1
  82. package/dist/@types/sensitive.d.ts +56 -0
  83. package/dist/@types/sensitive.d.ts.map +1 -0
  84. package/dist/@types/test/index.d.ts +1 -0
  85. package/dist/@types/test/index.d.ts.map +1 -1
  86. package/dist/@types/test/sandbox.d.ts +2 -26
  87. package/dist/@types/test/sandbox.d.ts.map +1 -1
  88. package/dist/@types/types/act.d.ts +216 -0
  89. package/dist/@types/types/act.d.ts.map +1 -0
  90. package/dist/@types/types/action.d.ts +67 -0
  91. package/dist/@types/types/action.d.ts.map +1 -1
  92. package/dist/@types/types/builders.d.ts +722 -0
  93. package/dist/@types/types/builders.d.ts.map +1 -0
  94. package/dist/@types/types/errors.d.ts +31 -1
  95. package/dist/@types/types/errors.d.ts.map +1 -1
  96. package/dist/@types/types/index.d.ts +38 -0
  97. package/dist/@types/types/index.d.ts.map +1 -1
  98. package/dist/@types/types/ports.d.ts +16 -10
  99. package/dist/@types/types/ports.d.ts.map +1 -1
  100. package/dist/@types/types/reaction.d.ts +11 -1
  101. package/dist/@types/types/reaction.d.ts.map +1 -1
  102. package/dist/@types/types/sandbox.d.ts +31 -0
  103. package/dist/@types/types/sandbox.d.ts.map +1 -0
  104. package/dist/@types/types/schemas.d.ts +12 -17
  105. package/dist/@types/types/schemas.d.ts.map +1 -1
  106. package/dist/{chunk-F7K7SIG6.js → chunk-2PMUONGF.js} +38 -57
  107. package/dist/chunk-2PMUONGF.js.map +1 -0
  108. package/dist/chunk-HF433MAF.cjs +264 -0
  109. package/dist/chunk-HF433MAF.cjs.map +1 -0
  110. package/dist/{chunk-5FXT63KF.js → chunk-JABYJGT7.js} +184 -24
  111. package/dist/chunk-JABYJGT7.js.map +1 -0
  112. package/dist/chunk-VE3MTY4A.cjs +1233 -0
  113. package/dist/chunk-VE3MTY4A.cjs.map +1 -0
  114. package/dist/index.cjs +1615 -3003
  115. package/dist/index.cjs.map +1 -1
  116. package/dist/index.js +751 -813
  117. package/dist/index.js.map +1 -1
  118. package/dist/test/index.cjs +16 -1105
  119. package/dist/test/index.cjs.map +1 -1
  120. package/dist/test/index.js +2 -2
  121. package/dist/test/index.js.map +1 -1
  122. package/dist/types/index.cjs +58 -276
  123. package/dist/types/index.cjs.map +1 -1
  124. package/dist/types/index.js +15 -1
  125. package/package.json +1 -1
  126. package/dist/@types/builders/build-classify.d.ts.map +0 -1
  127. package/dist/@types/builders/builder-base.d.ts +0 -70
  128. package/dist/@types/builders/builder-base.d.ts.map +0 -1
  129. package/dist/@types/builders/reaction-builder.d.ts +0 -55
  130. package/dist/@types/builders/reaction-builder.d.ts.map +0 -1
  131. package/dist/@types/internal/close-signal.d.ts.map +0 -1
  132. package/dist/@types/internal/correlator.d.ts.map +0 -1
  133. package/dist/@types/internal/defer-signal.d.ts +0 -35
  134. package/dist/@types/internal/defer-signal.d.ts.map +0 -1
  135. package/dist/@types/internal/drain.d.ts.map +0 -1
  136. package/dist/@types/internal/index.d.ts +0 -43
  137. package/dist/@types/internal/index.d.ts.map +0 -1
  138. package/dist/@types/internal/sensitive.d.ts +0 -177
  139. package/dist/@types/internal/sensitive.d.ts.map +0 -1
  140. package/dist/chunk-5FXT63KF.js.map +0 -1
  141. package/dist/chunk-F7K7SIG6.js.map +0 -1
@@ -1,146 +1,5 @@
1
- /**
2
- * @module projection-builder
3
- * @category Builders
4
- *
5
- * Fluent builder for composing projection handlers — read-model updaters
6
- * that react to events and update external state (databases, caches, etc.).
7
- *
8
- * Projections differ from slices: they don't contain states, don't dispatch
9
- * actions, and are pure side-effect handlers routed to a named stream.
10
- */
11
- import type { ZodType } from "zod";
12
- import { type FoldConfig } from "../internal/index.js";
13
- import type { BatchHandler, CacheEntry, Committed, EventRegister, FoldOptions, ReactionResolver, Schema, Schemas, State } from "../types/index.js";
14
- /**
15
- * A self-contained projection grouping read-model update handlers.
16
- * Projections are composed into an Act orchestrator via `act().withProjection(projection)`.
17
- *
18
- * @template TEvents - Event schemas handled by this projection
19
- */
20
- export type Projection<TEvents extends Schemas> = {
21
- readonly _tag: "Projection";
22
- readonly events: EventRegister<TEvents>;
23
- readonly target?: string;
24
- readonly batchHandler?: BatchHandler<TEvents>;
25
- /**
26
- * State-fold spec from `.of()`. The builder only records intent — the
27
- * orchestrator resolves the REGISTRY-MERGED full state at
28
- * `act().build()` and synthesizes the batch handler there, so the
29
- * fold always covers every reducer of the state, including partials
30
- * merged by slices the projection never saw.
31
- * @internal
32
- */
33
- readonly fold?: {
34
- readonly name: string;
35
- readonly flush: (rows: ReadonlyArray<CacheEntry<any>>) => Promise<void>;
36
- readonly config: FoldConfig;
37
- };
38
- };
39
- /**
40
- * The `.of()` continuation: state projections flush the cache layer
41
- * outward — the rows ARE the streams' {@link CacheEntry} values, one
42
- * per dirty stream per flush round. Must be an idempotent upsert keyed
43
- * on `stream` (guard with `event_id` for order safety when a rebuild
44
- * races a live worker).
45
- */
46
- type FoldFlush<TState extends Schema, TE extends Schemas> = {
47
- flush: (handler: (rows: ReadonlyArray<CacheEntry<TState>>) => Promise<void>) => {
48
- build: () => Projection<TE>;
49
- };
50
- };
51
- /**
52
- * `.of()` accepts the partials of ONE state (same name, enforced at the
53
- * type level via `TName`) purely for typing and event registration —
54
- * the fold itself always runs on the registry-merged full state,
55
- * resolved at `act().build()`. Passing every partial is required: the
56
- * orchestrator validates completeness at build and throws on missing
57
- * events.
58
- */
59
- type OfSignatures = {
60
- <TS1 extends Schema, TE1 extends Schemas, TA1 extends Schemas, TN extends string>(s1: State<TS1, TE1, TA1, TN>, options?: FoldOptions): FoldFlush<TS1, TE1>;
61
- <TS1 extends Schema, TE1 extends Schemas, TA1 extends Schemas, TS2 extends Schema, TE2 extends Schemas, TA2 extends Schemas, TN extends string>(s1: State<TS1, TE1, TA1, TN>, s2: State<TS2, TE2, TA2, TN>, options?: FoldOptions): FoldFlush<TS1 & TS2, TE1 & TE2>;
62
- <TS1 extends Schema, TE1 extends Schemas, TA1 extends Schemas, TS2 extends Schema, TE2 extends Schemas, TA2 extends Schemas, TS3 extends Schema, TE3 extends Schemas, TA3 extends Schemas, TN extends string>(s1: State<TS1, TE1, TA1, TN>, s2: State<TS2, TE2, TA2, TN>, s3: State<TS3, TE3, TA3, TN>, options?: FoldOptions): FoldFlush<TS1 & TS2 & TS3, TE1 & TE2 & TE3>;
63
- <TS1 extends Schema, TE1 extends Schemas, TA1 extends Schemas, TS2 extends Schema, TE2 extends Schemas, TA2 extends Schemas, TS3 extends Schema, TE3 extends Schemas, TA3 extends Schemas, TS4 extends Schema, TE4 extends Schemas, TA4 extends Schemas, TN extends string>(s1: State<TS1, TE1, TA1, TN>, s2: State<TS2, TE2, TA2, TN>, s3: State<TS3, TE3, TA3, TN>, s4: State<TS4, TE4, TA4, TN>, options?: FoldOptions): FoldFlush<TS1 & TS2 & TS3 & TS4, TE1 & TE2 & TE3 & TE4>;
64
- };
65
- /** Helper: a single-key record mapping an event name to its Zod schema. */
66
- type EventEntry<TKey extends string = string, TData extends Schema = Schema> = {
67
- [P in TKey]: ZodType<TData>;
68
- };
69
- /** Infer the handler-result type after registering one event. */
70
- type DoResult<TEvents extends Schemas, TKey extends string, TData extends Schema, TTarget extends string | undefined = undefined> = ProjectionBuilder<TEvents & {
71
- [P in TKey]: TData;
72
- }, TTarget, true> & {
73
- to: (resolver: ReactionResolver<TEvents & {
74
- [P in TKey]: TData;
75
- }, TKey> | string) => ProjectionBuilder<TEvents & {
76
- [P in TKey]: TData;
77
- }, TTarget, true>;
78
- };
79
- /**
80
- * Fluent builder interface for composing projections.
81
- *
82
- * When a static target is provided via `projection("target")`, the builder
83
- * exposes a `.batch()` method for registering a batch handler that processes
84
- * all events in a single call.
85
- *
86
- * @template TEvents - Event schemas
87
- * @template TTarget - Static target string or undefined
88
- */
89
- export type ProjectionBuilder<TEvents extends Schemas, TTarget extends string | undefined = undefined, THasHandlers extends boolean = false> = {
90
- /**
91
- * Begins defining a projection handler for a specific event.
92
- *
93
- * Pass a `{ EventName: schema }` record — use shorthand `{ EventName }`
94
- * when the variable name matches the event name. The key becomes the
95
- * event name, the value the Zod schema.
96
- */
97
- on: <TKey extends string, TData extends Schema>(entry: EventEntry<TKey, TData>) => {
98
- do: (handler: (event: Committed<TEvents & {
99
- [P in TKey]: TData;
100
- }, TKey>, stream: string) => Promise<void>) => DoResult<TEvents, TKey, TData, TTarget>;
101
- };
102
- /**
103
- * Builds and returns the Projection data structure.
104
- */
105
- build: () => Projection<TEvents>;
106
- /**
107
- * The registered event schemas and their reaction maps.
108
- */
109
- readonly events: EventRegister<TEvents>;
110
- } & (TTarget extends string ? {
111
- /**
112
- * Registers a batch handler that processes all events in a single call.
113
- *
114
- * Only available on projections with a static target (`projection("target")`).
115
- * The handler receives a discriminated union of all declared events,
116
- * enabling bulk DB operations in a single transaction.
117
- *
118
- * When defined, the batch handler is always called — even for a single event.
119
- * Individual `.do()` handlers serve as fallback for projections without `.batch()`.
120
- */
121
- batch: (handler: BatchHandler<TEvents>) => {
122
- build: () => Projection<TEvents>;
123
- };
124
- } & (THasHandlers extends false ? {
125
- /**
126
- * Declares a state projection: fold every event of the given
127
- * state through its own reducers and flush one row per stream —
128
- * the queryable list of the aggregates themselves.
129
- *
130
- * The state is the filter: the projection consumes exactly the
131
- * state's event register, so in a multi-state app only that
132
- * state's streams are folded — and every event of a folded
133
- * stream reaches the reducer. Write amplification tracks the
134
- * distinct stream count, not the event count; `app.reset`
135
- * rebuilds in O(streams) upserts.
136
- *
137
- * The fluent chain enforces the shape: `.of()` is only offered
138
- * before any `.on()` handler, and narrows to `.flush()` +
139
- * `.build()` — a projection either folds a state or declares
140
- * handlers, never both.
141
- */
142
- of: OfSignatures;
143
- } : {}) : {});
1
+ import type { ProjectionBuilder } from "../types/builders.js";
2
+ import type { Schemas } from "../types/index.js";
144
3
  /**
145
4
  * Creates a new projection builder with a static target stream.
146
5
  *
@@ -156,5 +15,4 @@ export declare function projection<TEvents extends Schemas = {}>(target: string)
156
15
  * Use per-handler `.to()` to route events to different streams.
157
16
  */
158
17
  export declare function projection<TEvents extends Schemas = {}>(target?: undefined): ProjectionBuilder<TEvents, undefined>;
159
- export {};
160
18
  //# sourceMappingURL=projection-builder.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"projection-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/projection-builder.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"projection-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/projection-builder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EASV,OAAO,EAER,MAAM,mBAAmB,CAAC;AA8M3B;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,SAAS,OAAO,GAAG,EAAE,EACrD,MAAM,EAAE,MAAM,GACb,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AACtC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,SAAS,OAAO,GAAG,EAAE,EACrD,MAAM,CAAC,EAAE,SAAS,GACjB,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC"}
@@ -5,77 +5,8 @@
5
5
  * Fluent builder for composing partial states with scoped reactions into
6
6
  * self-contained functional slices (vertical slice architecture).
7
7
  */
8
- import type { DEFAULT_LANE } from "../ports.js";
9
- import type { Actor, EventRegister, LaneConfig, Schema, SchemaRegister, Schemas, State } from "../types/index.js";
10
- import type { BuilderBase } from "./builder-base.js";
11
- import type { Projection } from "./projection-builder.js";
12
- /**
13
- * A self-contained functional slice grouping partial states with their
14
- * scoped reactions. Slices are composed into an Act orchestrator via
15
- * `act().withSlice(slice)`.
16
- *
17
- * @template TSchemaReg - Schema register for states
18
- * @template TEvents - Event schemas from this slice's states
19
- * @template TActions - Action schemas from this slice's states
20
- * @template TStateMap - Map of state names to state schemas
21
- * @template TActor - Actor type extending base Actor
22
- */
23
- export type Slice<TSchemaReg extends SchemaRegister<TActions>, TEvents extends Schemas, TActions extends Schemas, TStateMap extends Record<string, Schema> = {}, TActor extends Actor = Actor, TLanes extends string = typeof DEFAULT_LANE> = {
24
- readonly _tag: "Slice";
25
- readonly states: Map<string, State<any, any, any>>;
26
- readonly events: EventRegister<TEvents>;
27
- readonly projections: ReadonlyArray<Projection<any>>;
28
- /**
29
- * Drain lanes declared on this slice via `.withLane(...)`.
30
- * `act().withSlice(slice)` merges these into the Act's lane set so
31
- * `.to({lane})` is statically checked at the slice's call site against
32
- * the lanes the slice itself declared.
33
- */
34
- readonly lanes: ReadonlyArray<LaneConfig>;
35
- /** @internal phantom field for type-level state schema tracking */
36
- readonly _S?: TSchemaReg;
37
- /** @internal phantom field for type-level state name tracking */
38
- readonly _M?: TStateMap;
39
- /** @internal phantom field for type-level actor tracking */
40
- readonly _TActor?: TActor;
41
- /** @internal phantom field for type-level lane union tracking */
42
- readonly _TLanes?: TLanes;
43
- };
44
- /**
45
- * Fluent builder interface for composing functional slices.
46
- *
47
- * Provides a chainable API for registering states and projections,
48
- * and defining reactions scoped to the slice's own events.
49
- *
50
- * @template TSchemaReg - Schema register for states
51
- * @template TEvents - Event schemas
52
- * @template TActions - Action schemas
53
- * @template TStateMap - Map of state names to state schemas
54
- * @template TActor - Actor type extending base Actor
55
- */
56
- export interface SliceBuilder<TSchemaReg extends SchemaRegister<TActions>, TEvents extends Schemas, TActions extends Schemas, TStateMap extends Record<string, Schema> = {}, TActor extends Actor = Actor, TLanes extends string = typeof DEFAULT_LANE> extends BuilderBase<SliceBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes>, TEvents, TActions, TActor, TLanes> {
57
- /**
58
- * Registers a state definition with the slice.
59
- *
60
- * Include every state whose actions your reaction handlers need to
61
- * dispatch. Duplicate registrations (same state in multiple slices)
62
- * are handled automatically at composition time.
63
- */
64
- withState: <TNewState extends Schema, TNewEvents extends Schemas, TNewActions extends Schemas, TNewName extends string = string>(state: State<TNewState, TNewEvents, TNewActions, TNewName>) => SliceBuilder<TSchemaReg & {
65
- [K in keyof TNewActions]: TNewState;
66
- }, TEvents & TNewEvents, TActions & TNewActions, TStateMap & {
67
- [K in TNewName]: TNewState;
68
- }, TActor, TLanes>;
69
- /**
70
- * Declares a drain lane on this slice. Merged into the
71
- * parent Act's lane set by `act().withSlice(slice)`.
72
- */
73
- withLane: <const TConfig extends LaneConfig>(config: TConfig) => SliceBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes | TConfig["name"]>;
74
- /**
75
- * Builds and returns the Slice data structure.
76
- */
77
- build: () => Slice<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes>;
78
- }
8
+ import type { SliceBuilder } from "../types/builders.js";
9
+ import type { Actor, Schema, SchemaRegister, Schemas } from "../types/index.js";
79
10
  /**
80
11
  * Creates a new slice builder for composing partial states with scoped reactions.
81
12
  *
@@ -1 +1 @@
1
- {"version":3,"file":"slice-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/slice-builder.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"slice-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/slice-builder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAqB,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,KAAK,EACV,KAAK,EAGL,MAAM,EACN,cAAc,EACd,OAAO,EAER,MAAM,mBAAmB,CAAC;AAM3B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,KAAK,CAEnB,UAAU,SAAS,cAAc,CAAC,QAAQ,CAAC,GAAG,EAAE,EAChD,OAAO,SAAS,OAAO,GAAG,EAAE,EAC5B,QAAQ,SAAS,OAAO,GAAG,EAAE,EAC7B,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,EAC7C,MAAM,SAAS,KAAK,GAAG,KAAK,KACzB,YAAY,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CA+ClE"}
@@ -1,378 +1,5 @@
1
- /**
2
- * @module state-builder
3
- * @category Builders
4
- *
5
- * Fluent interface for defining a strongly-typed state machine using Zod schemas.
6
- */
7
- import type { ZodType } from "zod";
8
- import { type AutoclosePolicy } from "../internal/index.js";
9
- import type { ActionHandler, ActionOptions, Actor, AutocloseArchiver, Committed, Invariant, PatchHandlers, Schema, Schemas, Snapshot, State, ZodTypes } from "../types/index.js";
10
- /**
11
- * Builder interface for defining a state with event sourcing.
12
- *
13
- * Provides a fluent API to configure the initial state, event types,
14
- * and event handlers (reducers) before moving to action configuration.
15
- *
16
- * @template TState - State schema type
17
- * @template TName - State name literal type
18
- *
19
- * @see {@link state} for usage examples
20
- * @see {@link ActionBuilder} for action configuration
21
- */
22
- export type StateBuilder<TState extends Schema, TName extends string = string> = {
23
- /**
24
- * Defines the initial state for new state instances.
25
- *
26
- * The init function is called when a new stream is created (first event).
27
- * It can accept initial data or return a default state.
28
- *
29
- * @param init - Function returning the initial state
30
- * @returns A builder with `.emits()` to declare event types
31
- *
32
- * @example
33
- * ```typescript
34
- * .init(() => ({ count: 0, created: new Date() }))
35
- * ```
36
- */
37
- init: (init: () => Readonly<TState>) => {
38
- /**
39
- * Declares the event types that this state can emit.
40
- *
41
- * Events represent facts that have happened - they should be named in past tense.
42
- * Each event is defined with a Zod schema for type safety and runtime validation.
43
- *
44
- * @template TEvents - Event schemas type
45
- * @param events - Object mapping event names to Zod schemas
46
- * @returns An ActionBuilder (with optional `.patch()` to override specific reducers)
47
- *
48
- * @example
49
- * ```typescript
50
- * .emits({
51
- * Incremented: z.object({ amount: z.number() }),
52
- * Decremented: z.object({ amount: z.number() }),
53
- * Reset: z.object({})
54
- * })
55
- * ```
56
- */
57
- emits: <TEvents extends Schemas>(events: ZodTypes<TEvents>) => ActionBuilder<TState, TEvents, {}, TName> & {
58
- /**
59
- * Overrides specific event reducers. Events without a custom patch
60
- * default to passthrough: `({ data }) => data` (event data merges
61
- * into state).
62
- *
63
- * @param patch - Partial map of event names to patch handler functions
64
- * @returns An ActionBuilder for defining actions
65
- *
66
- * @example Only override the events that need custom logic
67
- * ```typescript
68
- * .emits({ TicketOpened, TicketClosed, TicketResolved })
69
- * .patch({
70
- * TicketOpened: ({ data }) => {
71
- * const { message, messageId, userId, ...other } = data;
72
- * return { ...other, userId, messages: { [messageId]: { ... } } };
73
- * },
74
- * })
75
- * // TicketClosed and TicketResolved use passthrough
76
- * ```
77
- */
78
- patch: (patch: Partial<PatchHandlers<TState, TEvents>>) => ActionBuilder<TState, TEvents, {}, TName>;
79
- };
80
- };
81
- };
82
- /** Helper: a single-key record mapping a state name to its Zod schema. */
83
- type StateEntry<TKey extends string = string, TState extends Schema = Schema> = {
84
- [P in TKey]: ZodType<TState>;
85
- };
86
- /** Helper: a single-key record mapping an action name to its Zod schema. */
87
- type ActionEntry<TKey extends string = string, TNewActions extends Schema = Schema> = {
88
- [P in TKey]: ZodType<TNewActions>;
89
- };
90
- /**
91
- * Builder interface for defining actions (commands) on a state.
92
- *
93
- * Actions represent user/system intents to modify state. Each action is validated
94
- * against a schema, can have business rule invariants, and must emit one or more events.
95
- *
96
- * @template TState - State schema type
97
- * @template TEvents - Event schemas type
98
- * @template TActions - Action schemas type
99
- * @template TName - State name literal type
100
- * @template TSnap - `true` once `.snap(...)` has been called. Gates the
101
- * `.autocloses({ keep })` rolling-window option — a windowed close is
102
- * meaningless without snapshots, so `keep` only typechecks after
103
- * `.snap` in the chain.
104
- *
105
- * @see {@link state} for complete usage examples
106
- */
107
- export type ActionBuilder<TState extends Schema, TEvents extends Schemas, TActions extends Schemas, TName extends string = string, TSnap extends boolean = false> = {
108
- /**
109
- * Defines an action (command) that can be executed on this state.
110
- *
111
- * Actions represent intents to change state - they should be named in imperative form
112
- * (e.g., "CreateUser", "IncrementCounter", "PlaceOrder"). Actions are validated against
113
- * their schema and must emit at least one event.
114
- *
115
- * Pass a `{ ActionName: schema }` record — use shorthand `{ ActionName }`
116
- * when the variable name matches the action name. The key becomes the
117
- * action name, the value the Zod schema.
118
- *
119
- * Pass an optional second argument to declare a per-action retry
120
- * policy — the orchestrator retries this action on
121
- * {@link ConcurrencyError} up to `maxRetries` extra times, applying
122
- * `backoff` between attempts when set. Omit the argument to keep the
123
- * current single-attempt behavior (`ConcurrencyError` surfaces on
124
- * first conflict).
125
- *
126
- * @template TKey - Action name (string literal type)
127
- * @template TNewActions - Action payload schema type
128
- * @param entry - Single-key record `{ ActionName: schema }`
129
- * @param options - Optional per-action retry policy
130
- * ({@link ActionOptions}).
131
- * @returns An object with `.given()` and `.emit()` for further configuration
132
- *
133
- * @example Simple action without invariants
134
- * ```typescript
135
- * .on({ increment: z.object({ by: z.number() }) })
136
- * .emit((action) => ["Incremented", { amount: action.by }])
137
- * ```
138
- */
139
- on: <TKey extends string, TNewActions extends Schema>(entry: ActionEntry<TKey, TNewActions>, options?: ActionOptions) => {
140
- /**
141
- * Adds business rule invariants that must hold before the action can execute.
142
- *
143
- * Invariants are checked after loading the current state but before emitting
144
- * events. Each invariant pairs a `description` with a `valid(state, actor?)`
145
- * predicate — when a predicate returns `false`, the action throws
146
- * `InvariantError` carrying the description. All invariants must pass for
147
- * the action to succeed.
148
- *
149
- * @param rules - Array of {@link Invariant} objects (`{ description, valid }`)
150
- * @returns An object with `.emit()` to finalize the action
151
- *
152
- * @example
153
- * ```typescript
154
- * .given([
155
- * { description: "Must be active", valid: (state) => state.status === "active" },
156
- * { description: "Must be the owner", valid: (state, actor) => state.ownerId === actor?.id }
157
- * ])
158
- * ```
159
- */
160
- given: (rules: Invariant<TState>[]) => {
161
- /**
162
- * Defines the action handler that emits events.
163
- *
164
- * The handler receives the action payload and current state snapshot,
165
- * and must return one or more events to emit. Events are applied to state
166
- * via the patch handlers defined earlier.
167
- *
168
- * Pass a string event name for passthrough: the action payload becomes
169
- * the event data directly.
170
- *
171
- * @param handler - Function that returns events to emit, or event name string for passthrough
172
- * @returns The ActionBuilder for chaining more actions
173
- *
174
- * @example Custom handler
175
- * ```typescript
176
- * .emit((action, snapshot) => {
177
- * const newBalance = snapshot.state.balance + action.amount;
178
- * return ["Deposited", { amount: action.amount, newBalance }];
179
- * })
180
- * ```
181
- */
182
- emit: {
183
- /** Custom handler — receives `(action, snapshot)` and returns one
184
- * or more `[EventName, data]` tuples (or `undefined`). */
185
- (handler: ActionHandler<TState, TEvents, {
186
- [P in TKey]: TNewActions;
187
- }, TKey>): ActionBuilder<TState, TEvents, TActions & {
188
- [P in TKey]: TNewActions;
189
- }, TName, TSnap>;
190
- /** Passthrough — the action payload becomes the event data
191
- * directly. Must reference an event declared in `.emits()`. */
192
- (event_name: keyof TEvents & string): ActionBuilder<TState, TEvents, TActions & {
193
- [P in TKey]: TNewActions;
194
- }, TName, TSnap>;
195
- };
196
- };
197
- /**
198
- * Defines the action handler that emits events. Same two overloads as
199
- * the post-`.given()` form above:
200
- *
201
- * - **Function** — receives `(action, snapshot)` and returns one or
202
- * more `[EventName, data]` tuples (or `undefined`).
203
- * - **String** — passthrough: the action payload becomes the event
204
- * data directly. Must reference an event declared in `.emits()`.
205
- *
206
- * The two overloads are kept separate (rather than merged into a
207
- * `handler | string` union) so that TS contextual typing of the
208
- * function alternative isn't degraded by considering the string
209
- * branch — under the union form `TState` could collapse to its
210
- * `Schema` constraint inside the callback.
211
- *
212
- * @example Passthrough (action payload = event data)
213
- * ```typescript
214
- * .emit("Incremented")
215
- * ```
216
- */
217
- emit: {
218
- (handler: ActionHandler<TState, TEvents, {
219
- [P in TKey]: TNewActions;
220
- }, TKey>): ActionBuilder<TState, TEvents, TActions & {
221
- [P in TKey]: TNewActions;
222
- }, TName, TSnap>;
223
- (event_name: keyof TEvents & string): ActionBuilder<TState, TEvents, TActions & {
224
- [P in TKey]: TNewActions;
225
- }, TName, TSnap>;
226
- };
227
- };
228
- /**
229
- * Defines a snapshotting strategy to optimize state reconstruction.
230
- *
231
- * Snapshots store the current state at a point in time, allowing faster state loading
232
- * by avoiding replaying all events from the beginning. The snap function is called
233
- * after each event is applied and should return `true` when a snapshot should be taken.
234
- *
235
- * @param snap - Predicate function that returns true when a snapshot should be taken
236
- * @returns The ActionBuilder for chaining
237
- *
238
- * @example Snapshot every 10 events
239
- * ```typescript
240
- * .snap((snapshot) => snapshot.patches >= 10)
241
- * ```
242
- */
243
- snap: (snap: (snapshot: Snapshot<TState, TEvents>) => boolean) => ActionBuilder<TState, TEvents, TActions, TName, true>;
244
- /**
245
- * Declares the disclosure predicate for `sensitive(...)`-marked event
246
- * fields. Gates external reads: returning `true` allows the actor to see
247
- * plaintext on the event; returning `false` substitutes `"[REDACTED]"`.
248
- * When absent, the framework default-denies on every external read —
249
- * fail-safe.
250
- *
251
- * One predicate per state. A second `.discloses(...)` call replaces the
252
- * first (same shape as snapshots being state-level, not per-event).
253
- *
254
- * The predicate receives the full event including merged PII so it can
255
- * branch on the payload itself (e.g.
256
- * `event.data.ownerId === actor.id`). Reducers, projections, and
257
- * reactions are unaffected — they follow separate visibility rules.
258
- *
259
- * @param disclose - Predicate `(event, actor) => boolean`. `true` =
260
- * plaintext, `false` = `"[REDACTED]"` substitution.
261
- * @returns The ActionBuilder for chaining.
262
- *
263
- * @example Owner-or-admin disclosure
264
- * ```typescript
265
- * state({ User: userSchema })
266
- * .init(() => ({ ... }))
267
- * .emits({ UserRegistered: z.object({ email: sensitive(z.string()) }) })
268
- * .discloses((event, actor) =>
269
- * actor.id === event.stream || actor.roles?.includes("admin"))
270
- * ```
271
- */
272
- discloses: (disclose: (event: Committed<TEvents, keyof TEvents & string>, actor: Actor) => boolean) => ActionBuilder<TState, TEvents, TActions, TName, TSnap>;
273
- /**
274
- * Declares the online close predicate for this state. The
275
- * orchestrator's autoclose cycle iterates the state's streams once
276
- * per tick and calls the predicate per candidate; truthy results are
277
- * scheduled for atomic truncate-and-seed via `Store.truncate` on the
278
- * next batch.
279
- *
280
- * One predicate per state. A second `.autocloses(...)` call replaces
281
- * the first (same shape as `.snap` / `.discloses` — state-level, not
282
- * per-event). Absent → the state opts out of online close entirely;
283
- * the cycle skips it and pays zero per-tick cost for it.
284
- *
285
- * Pass a declarative {@link AutoclosePolicy} object literal covering the
286
- * three operational pressure points (`after`, `is`, `reaches`). Top-level
287
- * fields combine with AND; an optional `or: {...}` block opens an
288
- * alternative OR path. Validated via Zod at build time; misconfiguration
289
- * throws before `act().build()` completes.
290
- *
291
- * Under the hood this compiles to a synthesized reaction that runs
292
- * on a per-aggregate synthetic stream: it defers to `head.created + the
293
- * policy's min after` while the cooldown holds and closes the stream once
294
- * the policy matches. There is no background sweep.
295
- *
296
- * **The function-predicate form was removed.** `.autocloses` no
297
- * longer accepts `(stream, head, count) => boolean`; an opaque predicate has
298
- * no derivable due-time or terminal event to react to. For conditions the
299
- * declarative form can't express, call `app.close(...)` from your own logic.
300
- *
301
- * @param policy The declarative {@link AutoclosePolicy} bag.
302
- * @returns The ActionBuilder for chaining.
303
- *
304
- * @example Declarative — cooldown after terminal (a Ticket closes
305
- * 90 days after resolution).
306
- * ```typescript
307
- * .autocloses({ is: "TicketResolved", after: { days: 90 } })
308
- * ```
309
- */
310
- autocloses: (policy: [TSnap] extends [true] ? AutoclosePolicy : Omit<AutoclosePolicy, "keep"> & {
311
- /** Rolling-window retention requires `.snap(...)` earlier in
312
- * the builder chain — a windowed close prunes behind a real
313
- * snapshot, so a state that never snapshots has nothing to
314
- * prune behind. */
315
- keep?: never;
316
- }) => ActionBuilder<TState, TEvents, TActions, TName, TSnap>;
317
- /**
318
- * Declares the archiver the online close cycle runs **before**
319
- * truncating a stream this state's `.autocloses(...)` predicate
320
- * accepted. Hosts use it to write events to durable storage (S3,
321
- * an analytics warehouse, cold tier) before the tombstone lands,
322
- * so the truncate doesn't lose history that the operator still
323
- * needs.
324
- *
325
- * Threads into `CloseTarget.archive` via the same plumbing
326
- * `app.close({ stream, archive })` already uses — the cycle holds
327
- * the stream's guard while the archiver runs, and a thrown
328
- * archiver leaves the stream guarded but un-truncated. No partial
329
- * truncate state, no data loss. It is not retried automatically;
330
- * `app.close([{ stream, archive }])` resumes the guarded stream.
331
- *
332
- * One archiver per state. A second `.archives(...)` call replaces
333
- * the first (same shape as `.snap` / `.discloses` /
334
- * `.autocloses`). Absent → the cycle truncates without an archive
335
- * step.
336
- *
337
- * @param archive `(stream, head) => Promise<void>`. Runs while
338
- * the stream is locked against new writes; the truncate runs
339
- * immediately after a successful resolve.
340
- * @returns The ActionBuilder for chaining.
341
- *
342
- * @example Archive to S3 before truncate.
343
- * ```typescript
344
- * state({ Ticket: ticketSchema })
345
- * .emits({ TicketOpened, TicketResolved })
346
- * // ...
347
- * .autocloses({ is: "TicketResolved" })
348
- * .archives(async (stream) => {
349
- * const events = await loadEvents(stream);
350
- * await s3.upload(`tickets/${stream}.jsonl`, events);
351
- * })
352
- * ```
353
- */
354
- archives: (archive: AutocloseArchiver<TEvents>) => ActionBuilder<TState, TEvents, TActions, TName, TSnap>;
355
- /**
356
- * Finalizes and builds the state definition.
357
- *
358
- * Call this method after defining all actions, invariants, and patches to create
359
- * the complete State object that can be registered with Act.
360
- *
361
- * @returns The complete strongly-typed State definition
362
- *
363
- * @example
364
- * ```typescript
365
- * const Counter = state({ Counter: schema })
366
- * .init(() => ({ count: 0 }))
367
- * .emits({ Incremented: z.object({ amount: z.number() }) })
368
- * .patch({ Incremented: ({ data }, state) => ({ count: state.count + data.amount }) })
369
- * .on({ increment: z.object({ by: z.number() }) })
370
- * .emit((action) => ["Incremented", { amount: action.by }])
371
- * .build(); // Returns State<TState, TEvents, TActions, TName>
372
- * ```
373
- */
374
- build: () => State<TState, TEvents, TActions, TName>;
375
- };
1
+ import type { StateBuilder, StateEntry } from "../types/builders.js";
2
+ import type { Schema } from "../types/index.js";
376
3
  /**
377
4
  * Creates a new state definition with event sourcing capabilities.
378
5
  *
@@ -417,5 +44,4 @@ export type ActionBuilder<TState extends Schema, TEvents extends Schemas, TActio
417
44
  * @see {@link https://rotorsoft.github.io/act-root/docs/examples/calculator | Calculator Example}
418
45
  */
419
46
  export declare function state<TName extends string, TState extends Schema>(entry: StateEntry<TName, TState>): StateBuilder<TState, TName>;
420
- export {};
421
47
  //# sourceMappingURL=state-builder.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"state-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/state-builder.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"state-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/state-builder.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAGV,YAAY,EACZ,UAAU,EACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAYV,MAAM,EAKP,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM,EAC/D,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,GAC/B,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAmD7B"}