@rotorsoft/act 0.35.1 → 0.35.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/dist/.tsbuildinfo +1 -0
- package/dist/@types/act.d.ts +672 -0
- package/dist/@types/act.d.ts.map +1 -0
- package/dist/@types/adapters/console-logger.d.ts +41 -0
- package/dist/@types/adapters/console-logger.d.ts.map +1 -0
- package/dist/@types/adapters/in-memory-cache.d.ts +34 -0
- package/dist/@types/adapters/in-memory-cache.d.ts.map +1 -0
- package/dist/@types/adapters/in-memory-store.d.ts +202 -0
- package/dist/@types/adapters/in-memory-store.d.ts.map +1 -0
- package/dist/@types/adapters/index.d.ts +4 -0
- package/dist/@types/adapters/index.d.ts.map +1 -0
- package/dist/@types/builders/act-builder.d.ts +160 -0
- package/dist/@types/builders/act-builder.d.ts.map +1 -0
- package/dist/@types/builders/index.d.ts +13 -0
- package/dist/@types/builders/index.d.ts.map +1 -0
- package/dist/@types/builders/projection-builder.d.ts +101 -0
- package/dist/@types/builders/projection-builder.d.ts.map +1 -0
- package/dist/@types/builders/slice-builder.d.ts +109 -0
- package/dist/@types/builders/slice-builder.d.ts.map +1 -0
- package/dist/@types/builders/state-builder.d.ts +424 -0
- package/dist/@types/builders/state-builder.d.ts.map +1 -0
- package/dist/@types/config.d.ts +119 -0
- package/dist/@types/config.d.ts.map +1 -0
- package/dist/@types/index.d.ts +14 -0
- package/dist/@types/index.d.ts.map +1 -0
- package/dist/@types/internal/build-classify.d.ts +44 -0
- package/dist/@types/internal/build-classify.d.ts.map +1 -0
- package/dist/@types/internal/close-cycle.d.ts +38 -0
- package/dist/@types/internal/close-cycle.d.ts.map +1 -0
- package/dist/@types/internal/correlate-cycle.d.ts +78 -0
- package/dist/@types/internal/correlate-cycle.d.ts.map +1 -0
- package/dist/@types/internal/drain-cycle.d.ts +113 -0
- package/dist/@types/internal/drain-cycle.d.ts.map +1 -0
- package/dist/@types/internal/drain-ratio.d.ts +26 -0
- package/dist/@types/internal/drain-ratio.d.ts.map +1 -0
- package/dist/@types/internal/drain.d.ts +41 -0
- package/dist/@types/internal/drain.d.ts.map +1 -0
- package/dist/@types/internal/event-sourcing.d.ts +96 -0
- package/dist/@types/internal/event-sourcing.d.ts.map +1 -0
- package/dist/@types/internal/index.d.ts +29 -0
- package/dist/@types/internal/index.d.ts.map +1 -0
- package/dist/@types/internal/merge.d.ts +31 -0
- package/dist/@types/internal/merge.d.ts.map +1 -0
- package/dist/@types/internal/reactions.d.ts +54 -0
- package/dist/@types/internal/reactions.d.ts.map +1 -0
- package/dist/@types/internal/settle.d.ts +60 -0
- package/dist/@types/internal/settle.d.ts.map +1 -0
- package/dist/@types/internal/tracing.d.ts +45 -0
- package/dist/@types/internal/tracing.d.ts.map +1 -0
- package/dist/@types/lru-map.d.ts +50 -0
- package/dist/@types/lru-map.d.ts.map +1 -0
- package/dist/@types/ports.d.ts +196 -0
- package/dist/@types/ports.d.ts.map +1 -0
- package/dist/@types/signals.d.ts +2 -0
- package/dist/@types/signals.d.ts.map +1 -0
- package/dist/@types/types/action.d.ts +444 -0
- package/dist/@types/types/action.d.ts.map +1 -0
- package/dist/@types/types/errors.d.ts +284 -0
- package/dist/@types/types/errors.d.ts.map +1 -0
- package/dist/@types/types/index.d.ts +39 -0
- package/dist/@types/types/index.d.ts.map +1 -0
- package/dist/@types/types/ports.d.ts +617 -0
- package/dist/@types/types/ports.d.ts.map +1 -0
- package/dist/@types/types/reaction.d.ts +314 -0
- package/dist/@types/types/reaction.d.ts.map +1 -0
- package/dist/@types/types/registry.d.ts +74 -0
- package/dist/@types/types/registry.d.ts.map +1 -0
- package/dist/@types/types/schemas.d.ts +117 -0
- package/dist/@types/types/schemas.d.ts.map +1 -0
- package/dist/@types/utils.d.ts +54 -0
- package/dist/@types/utils.d.ts.map +1 -0
- package/dist/chunk-AGWZY6YT.js +127 -0
- package/dist/chunk-AGWZY6YT.js.map +1 -0
- package/dist/index.cjs +3144 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.js +2975 -0
- package/dist/index.js.map +1 -0
- package/dist/types/index.cjs +166 -0
- package/dist/types/index.cjs.map +1 -0
- package/dist/types/index.js +33 -0
- package/dist/types/index.js.map +1 -0
- package/package.json +6 -2
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import "./signals.js";
|
|
2
|
+
/**
|
|
3
|
+
* @packageDocumentation
|
|
4
|
+
* @module act
|
|
5
|
+
* Main entry point for the Act framework. Re-exports all core APIs.
|
|
6
|
+
*/
|
|
7
|
+
export * from "./act.js";
|
|
8
|
+
export * from "./adapters/index.js";
|
|
9
|
+
export * from "./builders/index.js";
|
|
10
|
+
export * from "./config.js";
|
|
11
|
+
export * from "./ports.js";
|
|
12
|
+
export * from "./types/index.js";
|
|
13
|
+
export * from "./utils.js";
|
|
14
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,cAAc,CAAC;AAEtB;;;;GAIG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC"}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module build-classify
|
|
3
|
+
* @category Internal
|
|
4
|
+
*
|
|
5
|
+
* Build-time classification of the registry + state map. The Act constructor
|
|
6
|
+
* needs four pre-computed inputs to wire its runtime subsystems:
|
|
7
|
+
*
|
|
8
|
+
* - `staticTargets` — known-up-front reaction targets (statics get
|
|
9
|
+
* subscribed once at init; dynamics scan per event)
|
|
10
|
+
* - `hasDynamicResolvers` — short-circuit flag for `correlate()`
|
|
11
|
+
* - `reactiveEvents` — event names with at least one reaction (drives
|
|
12
|
+
* the drain skip-flag in `do()` and `reset()`)
|
|
13
|
+
* - `eventToState` — event-name → owning state, for `close({restart})`
|
|
14
|
+
* seed loading in multi-state apps
|
|
15
|
+
*
|
|
16
|
+
* Pure function — single pass over events + states, fully testable without
|
|
17
|
+
* instantiating Act.
|
|
18
|
+
*
|
|
19
|
+
* @internal
|
|
20
|
+
*/
|
|
21
|
+
import type { Registry, Schema, SchemaRegister, Schemas, State } from "../types/index.js";
|
|
22
|
+
import type { StaticTarget } from "./correlate-cycle.js";
|
|
23
|
+
/**
|
|
24
|
+
* Classification result. Returned by {@link classifyRegistry}; consumed
|
|
25
|
+
* piecewise by Act's constructor.
|
|
26
|
+
*
|
|
27
|
+
* @internal
|
|
28
|
+
*/
|
|
29
|
+
export type Classification = {
|
|
30
|
+
readonly staticTargets: StaticTarget[];
|
|
31
|
+
readonly hasDynamicResolvers: boolean;
|
|
32
|
+
readonly reactiveEvents: ReadonlySet<string>;
|
|
33
|
+
readonly eventToState: ReadonlyMap<string, State<any, any, any>>;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* Walk the registry once to collect static reaction targets, the dynamic-
|
|
37
|
+
* resolvers flag, the set of reactive event names, and the event-to-state
|
|
38
|
+
* map. Static targets are deduplicated by (target, source) — two reactions
|
|
39
|
+
* routing to the same projection produce one subscription.
|
|
40
|
+
*
|
|
41
|
+
* @internal
|
|
42
|
+
*/
|
|
43
|
+
export declare function classifyRegistry<TSchemaReg extends SchemaRegister<TActions>, TEvents extends Schemas, TActions extends Schemas>(registry: Registry<TSchemaReg, TEvents, TActions>, states: ReadonlyMap<string, State<Schema, any, any>>): Classification;
|
|
44
|
+
//# sourceMappingURL=build-classify.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"build-classify.d.ts","sourceRoot":"","sources":["../../../src/internal/build-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,MAAM,EACN,cAAc,EACd,OAAO,EACP,KAAK,EACN,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,aAAa,EAAE,YAAY,EAAE,CAAC;IACvC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7C,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;CAClE,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,SAAS,cAAc,CAAC,QAAQ,CAAC,EAC3C,OAAO,SAAS,OAAO,EACvB,QAAQ,SAAS,OAAO,EAExB,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,EACjD,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,GACnD,cAAc,CA4ChB"}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module close-cycle
|
|
3
|
+
* @category Internal
|
|
4
|
+
*
|
|
5
|
+
* Pure orchestration of the close-the-books flow: scan stream heads,
|
|
6
|
+
* partition by reaction safety, guard with tombstones, optionally seed
|
|
7
|
+
* restart state, run user archive callbacks, atomically truncate, and
|
|
8
|
+
* update the cache.
|
|
9
|
+
*
|
|
10
|
+
* The Act orchestrator owns lifecycle (correlate gate, emit("closed")) and
|
|
11
|
+
* the registry-derived inputs (reactive-event count, event→state map). All
|
|
12
|
+
* sequential phase work between those state touches lives here.
|
|
13
|
+
*
|
|
14
|
+
* @internal
|
|
15
|
+
*/
|
|
16
|
+
import type { CloseResult, CloseTarget, Logger, State } from "../types/index.js";
|
|
17
|
+
import type { EsOps } from "./event-sourcing.js";
|
|
18
|
+
/**
|
|
19
|
+
* Dependencies the close cycle needs from the Act orchestrator. Decoupled
|
|
20
|
+
* from `Act` itself so the cycle can be exercised from tests in isolation.
|
|
21
|
+
*
|
|
22
|
+
* @internal
|
|
23
|
+
*/
|
|
24
|
+
export type CloseCycleDeps = {
|
|
25
|
+
readonly reactiveEventsSize: number;
|
|
26
|
+
readonly eventToState: ReadonlyMap<string, State<any, any, any>>;
|
|
27
|
+
readonly load: EsOps["load"];
|
|
28
|
+
readonly tombstone: EsOps["tombstone"];
|
|
29
|
+
readonly logger: Logger;
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* Run the full close cycle for the given targets. Caller owns the
|
|
33
|
+
* lifecycle event emission.
|
|
34
|
+
*
|
|
35
|
+
* @internal
|
|
36
|
+
*/
|
|
37
|
+
export declare function runCloseCycle(targets: CloseTarget[], deps: CloseCycleDeps): Promise<CloseResult>;
|
|
38
|
+
//# sourceMappingURL=close-cycle.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"close-cycle.d.ts","sourceRoot":"","sources":["../../../src/internal/close-cycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,MAAM,EAEN,KAAK,EACN,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IACjE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAcF;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,WAAW,EAAE,EACtB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,WAAW,CAAC,CAmDtB"}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module correlate-cycle
|
|
3
|
+
* @category Internal
|
|
4
|
+
*
|
|
5
|
+
* Correlation — the discovery half of the correlate→drain pair. Owns the
|
|
6
|
+
* lazy init (subscribe static targets, read cold-start watermark), the
|
|
7
|
+
* dynamic-resolver scan that registers new streams as events arrive, and
|
|
8
|
+
* the periodic timer that drives background discovery.
|
|
9
|
+
*
|
|
10
|
+
* The Act orchestrator passes registry + classification (which static
|
|
11
|
+
* targets to subscribe, whether any dynamic resolvers exist) at build
|
|
12
|
+
* time; everything past that lives here.
|
|
13
|
+
*
|
|
14
|
+
* @internal
|
|
15
|
+
*/
|
|
16
|
+
import type { Query, Registry, SchemaRegister, Schemas } from "../types/index.js";
|
|
17
|
+
import type { DrainOps } from "./drain.js";
|
|
18
|
+
/**
|
|
19
|
+
* Static resolver target collected at build time. Subscribed once during
|
|
20
|
+
* init; never re-evaluated.
|
|
21
|
+
*
|
|
22
|
+
* @property priority - Scheduling priority for the resolved target stream.
|
|
23
|
+
* Combined with peers via `max()` at build time when multiple reactions
|
|
24
|
+
* target the same stream — see `build-classify.ts`.
|
|
25
|
+
*
|
|
26
|
+
* @internal
|
|
27
|
+
*/
|
|
28
|
+
export type StaticTarget = {
|
|
29
|
+
readonly stream: string;
|
|
30
|
+
readonly source?: string;
|
|
31
|
+
readonly priority?: number;
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* Drives correlation for one Act instance. Owns the checkpoint, the
|
|
35
|
+
* subscribed-streams LRU, and the periodic timer.
|
|
36
|
+
*
|
|
37
|
+
* @internal
|
|
38
|
+
*/
|
|
39
|
+
export declare class CorrelateCycle<TSchemaReg extends SchemaRegister<TActions>, TEvents extends Schemas, TActions extends Schemas> {
|
|
40
|
+
private readonly registry;
|
|
41
|
+
private readonly staticTargets;
|
|
42
|
+
private readonly hasDynamicResolvers;
|
|
43
|
+
private readonly cd;
|
|
44
|
+
private readonly onInit?;
|
|
45
|
+
private _checkpoint;
|
|
46
|
+
private _initialized;
|
|
47
|
+
private _timer;
|
|
48
|
+
private readonly _subscribed;
|
|
49
|
+
constructor(registry: Registry<TSchemaReg, TEvents, TActions>, staticTargets: ReadonlyArray<StaticTarget>, hasDynamicResolvers: boolean, cd: DrainOps<TEvents>, maxSubscribedStreams: number, onInit?: (() => void) | undefined);
|
|
50
|
+
/** Last correlated event id. */
|
|
51
|
+
get checkpoint(): number;
|
|
52
|
+
/**
|
|
53
|
+
* Initialize correlation state on first call.
|
|
54
|
+
* - Reads max(at) from store as cold-start checkpoint
|
|
55
|
+
* - Subscribes static resolver targets (idempotent upsert)
|
|
56
|
+
* - Populates the subscribed-streams LRU
|
|
57
|
+
* - Fires `onInit` once (Act uses this to flag a cold-start drain)
|
|
58
|
+
*/
|
|
59
|
+
init(): Promise<void>;
|
|
60
|
+
/**
|
|
61
|
+
* Discover dynamic-resolver targets in the events past the checkpoint
|
|
62
|
+
* and register any new streams via `cd.subscribe`. Static targets are
|
|
63
|
+
* subscribed at init time, so this only walks dynamic resolvers.
|
|
64
|
+
*/
|
|
65
|
+
correlate(query?: Query): Promise<{
|
|
66
|
+
subscribed: number;
|
|
67
|
+
last_id: number;
|
|
68
|
+
}>;
|
|
69
|
+
/**
|
|
70
|
+
* Start a periodic correlation worker. Returns false if one is already
|
|
71
|
+
* running. Errors from `correlate()` are routed through `log()` so they
|
|
72
|
+
* land in the configured logger (the timer keeps running on failure).
|
|
73
|
+
*/
|
|
74
|
+
startPolling(query?: Query, frequency?: number, callback?: (subscribed: number) => void): boolean;
|
|
75
|
+
/** Stop the periodic correlation worker. Idempotent. */
|
|
76
|
+
stopPolling(): void;
|
|
77
|
+
}
|
|
78
|
+
//# sourceMappingURL=correlate-cycle.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"correlate-cycle.d.ts","sourceRoot":"","sources":["../../../src/internal/correlate-cycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EACV,KAAK,EAEL,QAAQ,EACR,cAAc,EACd,OAAO,EACR,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,cAAc,CACzB,UAAU,SAAS,cAAc,CAAC,QAAQ,CAAC,EAC3C,OAAO,SAAS,OAAO,EACvB,QAAQ,SAAS,OAAO;IAQtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,EAAE;IAEnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAX1B,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAyD;IACvE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;gBAG1B,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,EACjD,aAAa,EAAE,aAAa,CAAC,YAAY,CAAC,EAC1C,mBAAmB,EAAE,OAAO,EAC5B,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,EACtC,oBAAoB,EAAE,MAAM,EACX,MAAM,CAAC,GAAE,MAAM,IAAI,aAAA;IAKtC,gCAAgC;IAChC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B;;;;OAIG;IACG,SAAS,CACb,KAAK,GAAE,KAAgC,GACtC,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IA8EnD;;;;OAIG;IACH,YAAY,CACV,KAAK,GAAE,KAAU,EACjB,SAAS,SAAS,EAClB,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,GACtC,OAAO;IAgBV,wDAAwD;IACxD,WAAW,IAAI,IAAI;CAMpB"}
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module drain-cycle
|
|
3
|
+
* @category Internal
|
|
4
|
+
*
|
|
5
|
+
* Two layers of the drain pipeline:
|
|
6
|
+
*
|
|
7
|
+
* - {@link runDrainCycle} — pure function for one round-trip of
|
|
8
|
+
* claim → fetch → group → dispatch → ack/block. No orchestrator state.
|
|
9
|
+
* Reusable for property tests and standalone benchmarks.
|
|
10
|
+
*
|
|
11
|
+
* - {@link DrainController} — stateful driver that owns the armed flag,
|
|
12
|
+
* the concurrency lock, and the adaptive lag/lead ratio. Wraps
|
|
13
|
+
* `runDrainCycle` with the lifecycle decisions Act used to make inline.
|
|
14
|
+
*
|
|
15
|
+
* @internal
|
|
16
|
+
*/
|
|
17
|
+
import type { BatchHandler, BlockedLease, Drain, DrainOptions, Fetch, Lease, Logger, ReactionPayload, Registry, SchemaRegister, Schemas } from "../types/index.js";
|
|
18
|
+
import type { DrainOps } from "./drain.js";
|
|
19
|
+
/**
|
|
20
|
+
* Outcome of processing a single leased stream — produced by Act's `handle`
|
|
21
|
+
* / `handleBatch` dispatchers, consumed by `runDrainCycle` to drive ack/block.
|
|
22
|
+
*
|
|
23
|
+
* @internal
|
|
24
|
+
*/
|
|
25
|
+
export type HandleResult = Readonly<{
|
|
26
|
+
lease: Lease;
|
|
27
|
+
handled: number;
|
|
28
|
+
at: number;
|
|
29
|
+
error?: string;
|
|
30
|
+
block?: boolean;
|
|
31
|
+
}>;
|
|
32
|
+
/**
|
|
33
|
+
* Per-event reaction dispatcher signature (matches `Act.handle`).
|
|
34
|
+
* @internal
|
|
35
|
+
*/
|
|
36
|
+
export type Handle<TEvents extends Schemas> = (lease: Lease, payloads: ReactionPayload<TEvents>[]) => Promise<HandleResult>;
|
|
37
|
+
/**
|
|
38
|
+
* Bulk reaction dispatcher signature (matches `Act.handleBatch`).
|
|
39
|
+
* @internal
|
|
40
|
+
*/
|
|
41
|
+
export type HandleBatch<TEvents extends Schemas> = (lease: Lease, payloads: ReactionPayload<TEvents>[], batchHandler: BatchHandler<TEvents>) => Promise<HandleResult>;
|
|
42
|
+
/**
|
|
43
|
+
* One drain cycle's results. Returned by {@link runDrainCycle}; consumed by
|
|
44
|
+
* `Act.drain()` to update lifecycle state, the lag/lead ratio, and emit the
|
|
45
|
+
* `acked` / `blocked` lifecycle events.
|
|
46
|
+
*
|
|
47
|
+
* @internal
|
|
48
|
+
*/
|
|
49
|
+
export type DrainCycle<TEvents extends Schemas> = {
|
|
50
|
+
readonly leased: Lease[];
|
|
51
|
+
readonly fetched: Fetch<TEvents>;
|
|
52
|
+
readonly handled: HandleResult[];
|
|
53
|
+
readonly acked: Lease[];
|
|
54
|
+
readonly blocked: BlockedLease[];
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* Run one drain cycle: claim streams, fetch their events, dispatch
|
|
58
|
+
* matching reactions, ack the successes, block the retries-exhausted.
|
|
59
|
+
*
|
|
60
|
+
* Returns `undefined` when nothing was claimed — caller can short-circuit
|
|
61
|
+
* the rest of the drain pass.
|
|
62
|
+
*
|
|
63
|
+
* @internal
|
|
64
|
+
*/
|
|
65
|
+
export declare function runDrainCycle<TEvents extends Schemas, TActions extends Schemas, TSchemaReg extends SchemaRegister<TActions>>(ops: DrainOps<TEvents>, registry: Registry<TSchemaReg, TEvents, TActions>, batchHandlers: Map<string, BatchHandler<TEvents>>, handle: Handle<TEvents>, handleBatch: HandleBatch<TEvents>, lagging: number, leading: number, eventLimit: number, leaseMillis: number): Promise<DrainCycle<TEvents> | undefined>;
|
|
66
|
+
/**
|
|
67
|
+
* Dependencies the {@link DrainController} needs from the orchestrator.
|
|
68
|
+
* The lifecycle event sinks (`onAcked` / `onBlocked`) are callbacks so
|
|
69
|
+
* this module doesn't reach back into Act's emitter.
|
|
70
|
+
*
|
|
71
|
+
* @internal
|
|
72
|
+
*/
|
|
73
|
+
export type DrainControllerDeps<TEvents extends Schemas, TActions extends Schemas, TSchemaReg extends SchemaRegister<TActions>> = {
|
|
74
|
+
readonly logger: Logger;
|
|
75
|
+
readonly ops: DrainOps<TEvents>;
|
|
76
|
+
readonly registry: Registry<TSchemaReg, TEvents, TActions>;
|
|
77
|
+
readonly batchHandlers: Map<string, BatchHandler<TEvents>>;
|
|
78
|
+
readonly handle: Handle<TEvents>;
|
|
79
|
+
readonly handleBatch: HandleBatch<TEvents>;
|
|
80
|
+
readonly onAcked: (acked: Lease[]) => void;
|
|
81
|
+
readonly onBlocked: (blocked: BlockedLease[]) => void;
|
|
82
|
+
};
|
|
83
|
+
/**
|
|
84
|
+
* Stateful driver around {@link runDrainCycle}. Owns:
|
|
85
|
+
*
|
|
86
|
+
* - `_armed` — has any commit / reset / cold-start signaled work to do?
|
|
87
|
+
* - `_locked` — concurrent-call guard (overlapping `drain()` calls return
|
|
88
|
+
* an empty result instead of running twice)
|
|
89
|
+
* - `_ratio` — adaptive lag-to-lead frontier split, updated per cycle
|
|
90
|
+
*
|
|
91
|
+
* The orchestrator owns commits, lifecycle emission, and `arm()` triggers
|
|
92
|
+
* — the controller owns everything between those edges.
|
|
93
|
+
*
|
|
94
|
+
* @internal
|
|
95
|
+
*/
|
|
96
|
+
export declare class DrainController<TEvents extends Schemas, TActions extends Schemas, TSchemaReg extends SchemaRegister<TActions>> {
|
|
97
|
+
private readonly deps;
|
|
98
|
+
private _armed;
|
|
99
|
+
private _locked;
|
|
100
|
+
private _ratio;
|
|
101
|
+
constructor(deps: DrainControllerDeps<TEvents, TActions, TSchemaReg>);
|
|
102
|
+
/**
|
|
103
|
+
* Signal that a commit (or reset / cold-start) may have produced work.
|
|
104
|
+
* Subsequent `drain()` calls will run the pipeline; once the pipeline
|
|
105
|
+
* settles to no-progress, the controller disarms itself.
|
|
106
|
+
*/
|
|
107
|
+
arm(): void;
|
|
108
|
+
/** Read-only flag — true while a commit / reset is unprocessed. */
|
|
109
|
+
get armed(): boolean;
|
|
110
|
+
/** Run one drain pass. Short-circuits when not armed or already running. */
|
|
111
|
+
drain({ streamLimit, eventLimit, leaseMillis, }?: DrainOptions): Promise<Drain<TEvents>>;
|
|
112
|
+
}
|
|
113
|
+
//# sourceMappingURL=drain-cycle.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"drain-cycle.d.ts","sourceRoot":"","sources":["../../../src/internal/drain-cycle.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module drain-ratio
|
|
3
|
+
* @category Internal
|
|
4
|
+
*
|
|
5
|
+
* Adaptive lag-to-lead ratio for the dual-frontier drain strategy.
|
|
6
|
+
*
|
|
7
|
+
* The orchestrator splits its per-cycle stream budget between two frontiers:
|
|
8
|
+
*
|
|
9
|
+
* - **lagging** — newly subscribed or behind streams catching up.
|
|
10
|
+
* - **leading** — actively-processing streams at the head of the log.
|
|
11
|
+
*
|
|
12
|
+
* After each cycle, this helper looks at how many events were actually
|
|
13
|
+
* handled in each frontier and shifts the next cycle's split toward
|
|
14
|
+
* whichever frontier had the higher per-stream throughput. The result is
|
|
15
|
+
* clamped to `[0.2, 0.8]` so neither frontier can be starved.
|
|
16
|
+
*
|
|
17
|
+
* @internal
|
|
18
|
+
*/
|
|
19
|
+
import type { HandleResult } from "./drain-cycle.js";
|
|
20
|
+
/**
|
|
21
|
+
* Compute the next lag-to-lead ratio from the cycle's handled events and
|
|
22
|
+
* the frontier sizes used to claim them. Returns `RATIO_DEFAULT` when no
|
|
23
|
+
* progress was made (nothing to base a decision on).
|
|
24
|
+
*/
|
|
25
|
+
export declare function computeLagLeadRatio(handled: ReadonlyArray<HandleResult>, lagging: number, leading: number): number;
|
|
26
|
+
//# sourceMappingURL=drain-ratio.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"drain-ratio.d.ts","sourceRoot":"","sources":["../../../src/internal/drain-ratio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQrD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,MAAM,CAYR"}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module drain
|
|
3
|
+
* @category Internal
|
|
4
|
+
*
|
|
5
|
+
* Pipeline operations consumed by the drain/correlate loop. Each op is a
|
|
6
|
+
* single async step the orchestrator invokes per drain cycle:
|
|
7
|
+
*
|
|
8
|
+
* - `claim` — atomically discover and lock streams for processing
|
|
9
|
+
* - `fetch` — read events for each leased stream
|
|
10
|
+
* - `ack` — release leases for successfully handled streams
|
|
11
|
+
* - `block` — flag leases that exceeded the retry budget
|
|
12
|
+
* - `subscribe` — register newly correlated streams with the store
|
|
13
|
+
*
|
|
14
|
+
* This module exposes only the bare implementations as plain async functions,
|
|
15
|
+
* mirroring the shape of {@link "event-sourcing"}. Trace decoration is
|
|
16
|
+
* layered on top in {@link "tracing"} and selected by the orchestrator at
|
|
17
|
+
* construction time. No tracing imports here.
|
|
18
|
+
*
|
|
19
|
+
* @internal
|
|
20
|
+
*/
|
|
21
|
+
import type { BlockedLease, Fetch, Lease, Schemas } from "../types/index.js";
|
|
22
|
+
/** @internal */
|
|
23
|
+
export interface DrainOps<TEvents extends Schemas> {
|
|
24
|
+
claim: typeof claim;
|
|
25
|
+
fetch: typeof fetch<TEvents>;
|
|
26
|
+
ack: typeof ack;
|
|
27
|
+
block: typeof block;
|
|
28
|
+
subscribe: typeof subscribe;
|
|
29
|
+
}
|
|
30
|
+
export declare const claim: (lagging: number, leading: number, by: string, millis: number) => Promise<Lease[]>;
|
|
31
|
+
export declare function fetch<TEvents extends Schemas>(leased: Lease[], eventLimit: number): Promise<Fetch<TEvents>>;
|
|
32
|
+
export declare const ack: (leases: Lease[]) => Promise<Lease[]>;
|
|
33
|
+
export declare const block: (leases: BlockedLease[]) => Promise<BlockedLease[]>;
|
|
34
|
+
export declare const subscribe: (streams: Array<{
|
|
35
|
+
stream: string;
|
|
36
|
+
source?: string;
|
|
37
|
+
}>) => Promise<{
|
|
38
|
+
subscribed: number;
|
|
39
|
+
watermark: number;
|
|
40
|
+
}>;
|
|
41
|
+
//# sourceMappingURL=drain.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"drain.d.ts","sourceRoot":"","sources":["../../../src/internal/drain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EACV,YAAY,EAEZ,KAAK,EACL,KAAK,EACL,OAAO,EACR,MAAM,mBAAmB,CAAC;AAE3B,gBAAgB;AAChB,MAAM,WAAW,QAAQ,CAAC,OAAO,SAAS,OAAO;IAC/C,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,KAAK,EAAE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,GAAG,EAAE,OAAO,GAAG,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,SAAS,EAAE,OAAO,SAAS,CAAC;CAC7B;AAED,eAAO,MAAM,KAAK,GAChB,SAAS,MAAM,EACf,SAAS,MAAM,EACf,IAAI,MAAM,EACV,QAAQ,MAAM,KACb,OAAO,CAAC,KAAK,EAAE,CAAgD,CAAC;AAEnE,wBAAsB,KAAK,CAAC,OAAO,SAAS,OAAO,EACjD,MAAM,EAAE,KAAK,EAAE,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAYzB;AAED,eAAO,MAAM,GAAG,GAAI,QAAQ,KAAK,EAAE,KAAG,OAAO,CAAC,KAAK,EAAE,CAAwB,CAAC;AAE9E,eAAO,MAAM,KAAK,GAAI,QAAQ,YAAY,EAAE,KAAG,OAAO,CAAC,YAAY,EAAE,CAC9C,CAAC;AAExB,eAAO,MAAM,SAAS,GACpB,SAAS,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,KAClD,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CACxB,CAAC"}
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module event-sourcing
|
|
3
|
+
* @category Internal
|
|
4
|
+
*
|
|
5
|
+
* Pure event-sourcing primitives: `snap` persists state checkpoints, `load`
|
|
6
|
+
* reconstructs state by replaying events through reducers, and `action`
|
|
7
|
+
* validates an action, runs invariants, emits events, and commits them
|
|
8
|
+
* atomically. `tombstone` commits the close-the-books guard with optimistic
|
|
9
|
+
* concurrency.
|
|
10
|
+
*
|
|
11
|
+
* These are the bare implementations — observability is layered on top in
|
|
12
|
+
* {@link "tracing"} and wired by the orchestrator at construction time.
|
|
13
|
+
* No tracing imports here, no module-level mutable state.
|
|
14
|
+
*
|
|
15
|
+
* @internal
|
|
16
|
+
*/
|
|
17
|
+
import type { AsOf, Committed, Schema, Schemas, Snapshot, State, Target } from "../types/index.js";
|
|
18
|
+
/** @internal */
|
|
19
|
+
export interface EsOps {
|
|
20
|
+
snap: typeof snap;
|
|
21
|
+
load: typeof load;
|
|
22
|
+
action: typeof action;
|
|
23
|
+
tombstone: typeof tombstone;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Event sourcing utilities for snapshotting, loading, and committing actions/events.
|
|
27
|
+
* Used internally by Act and state machines.
|
|
28
|
+
*/
|
|
29
|
+
/**
|
|
30
|
+
* Saves a snapshot of the state to the store.
|
|
31
|
+
*
|
|
32
|
+
* Snapshots are used to optimize state reconstruction for aggregates with long event streams.
|
|
33
|
+
*
|
|
34
|
+
* @template TState The type of state
|
|
35
|
+
* @template TEvents The type of events
|
|
36
|
+
* @param snapshot The snapshot to save
|
|
37
|
+
* @returns Promise that resolves when the snapshot is saved
|
|
38
|
+
*
|
|
39
|
+
* @example
|
|
40
|
+
* await snap(snapshot);
|
|
41
|
+
*/
|
|
42
|
+
export declare function snap<TState extends Schema, TEvents extends Schemas>(snapshot: Snapshot<TState, TEvents>): Promise<void>;
|
|
43
|
+
/**
|
|
44
|
+
* Commits a tombstone event with optimistic concurrency, returning the
|
|
45
|
+
* committed record on success or `undefined` if the stream moved past
|
|
46
|
+
* `expectedVersion` (concurrent write detected). Other store errors
|
|
47
|
+
* propagate.
|
|
48
|
+
*
|
|
49
|
+
* Used by `close()` to guard a stream while archive/truncate runs:
|
|
50
|
+
* subsequent `action()` calls see the tombstone at head and reject with
|
|
51
|
+
* {@link StreamClosedError} until the close completes.
|
|
52
|
+
*
|
|
53
|
+
* @internal
|
|
54
|
+
*/
|
|
55
|
+
export declare function tombstone(stream: string, expectedVersion: number, correlation: string): Promise<Committed<Schemas, keyof Schemas> | undefined>;
|
|
56
|
+
/**
|
|
57
|
+
* Loads a snapshot of the state from the store by replaying events and applying patches.
|
|
58
|
+
*
|
|
59
|
+
* First checks the cache for a checkpoint, then queries the store for events
|
|
60
|
+
* committed after the cached position. On cache miss, replays from the store
|
|
61
|
+
* (using snapshots if available to avoid full replay).
|
|
62
|
+
*
|
|
63
|
+
* @template TState The type of state
|
|
64
|
+
* @template TEvents The type of events
|
|
65
|
+
* @template TActions The type of actions
|
|
66
|
+
* @param me The state machine definition
|
|
67
|
+
* @param stream The stream (instance) to load
|
|
68
|
+
* @param callback (Optional) Callback to receive the loaded snapshot as it is built
|
|
69
|
+
* @returns The snapshot of the loaded state
|
|
70
|
+
*
|
|
71
|
+
* @example
|
|
72
|
+
* const snapshot = await load(Counter, "counter1");
|
|
73
|
+
*/
|
|
74
|
+
export declare function load<TState extends Schema, TEvents extends Schemas, TActions extends Schemas>(me: State<TState, TEvents, TActions>, stream: string, callback?: (snapshot: Snapshot<TState, TEvents>) => void, asOf?: AsOf): Promise<Snapshot<TState, TEvents>>;
|
|
75
|
+
/**
|
|
76
|
+
* Executes an action and emits an event to be committed by the store.
|
|
77
|
+
*
|
|
78
|
+
* This function validates the action, applies business invariants, emits events, and commits them to the event store.
|
|
79
|
+
*
|
|
80
|
+
* @template TState The type of state
|
|
81
|
+
* @template TEvents The type of events
|
|
82
|
+
* @template TActions The type of actionSchemas
|
|
83
|
+
* @template TKey The type of action to execute
|
|
84
|
+
* @param me The state machine definition
|
|
85
|
+
* @param action The action to execute
|
|
86
|
+
* @param target The target (stream, actor, etc.)
|
|
87
|
+
* @param payload The payload of the action
|
|
88
|
+
* @param reactingTo (Optional) The event that the action is reacting to
|
|
89
|
+
* @param skipValidation (Optional) Whether to skip validation (not recommended)
|
|
90
|
+
* @returns The snapshot of the committed event
|
|
91
|
+
*
|
|
92
|
+
* @example
|
|
93
|
+
* const snapshot = await action(Counter, "increment", { stream: "counter1", actor }, { by: 1 });
|
|
94
|
+
*/
|
|
95
|
+
export declare function action<TState extends Schema, TEvents extends Schemas, TActions extends Schemas, TKey extends keyof TActions>(me: State<TState, TEvents, TActions>, action: TKey, target: Target, payload: Readonly<TActions[TKey]>, reactingTo?: Committed<Schemas, keyof Schemas>, skipValidation?: boolean): Promise<Snapshot<TState, TEvents>[]>;
|
|
96
|
+
//# sourceMappingURL=event-sourcing.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"event-sourcing.d.ts","sourceRoot":"","sources":["../../../src/internal/event-sourcing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAUH,OAAO,KAAK,EACV,IAAI,EACJ,SAAS,EAGT,MAAM,EACN,OAAO,EACP,QAAQ,EACR,KAAK,EACL,MAAM,EACP,MAAM,mBAAmB,CAAC;AAG3B,gBAAgB;AAChB,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,OAAO,IAAI,CAAC;IAClB,IAAI,EAAE,OAAO,IAAI,CAAC;IAClB,MAAM,EAAE,OAAO,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,SAAS,CAAC;CAC7B;AAED;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CAAC,MAAM,SAAS,MAAM,EAAE,OAAO,SAAS,OAAO,EACvE,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,GAAG,SAAS,CAAC,CAaxD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,IAAI,CACxB,MAAM,SAAS,MAAM,EACrB,OAAO,SAAS,OAAO,EACvB,QAAQ,SAAS,OAAO,EAExB,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EACpC,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EACxD,IAAI,CAAC,EAAE,IAAI,GACV,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA0EpC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,MAAM,CAC1B,MAAM,SAAS,MAAM,EACrB,OAAO,SAAS,OAAO,EACvB,QAAQ,SAAS,OAAO,EACxB,IAAI,SAAS,MAAM,QAAQ,EAE3B,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EACpC,MAAM,EAAE,IAAI,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EACjC,UAAU,CAAC,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,EAC9C,cAAc,UAAQ,GACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAiItC"}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module internal
|
|
3
|
+
* @category Internal
|
|
4
|
+
*
|
|
5
|
+
* Barrel for framework-internal modules. These exports are not part of the
|
|
6
|
+
* public package API and may change between minors. Anything reachable from
|
|
7
|
+
* `@rotorsoft/act`'s top-level barrel (`src/index.ts`) is the public surface;
|
|
8
|
+
* what lives here is implementation detail used by `Act`, the builders, and
|
|
9
|
+
* the orchestrator's pipelines.
|
|
10
|
+
*
|
|
11
|
+
* Only symbols actually consumed *via this barrel* from outside `internal/`
|
|
12
|
+
* are re-exported here. Modules within `internal/` import each other
|
|
13
|
+
* directly by file path; production code in `adapters/` and tests that
|
|
14
|
+
* need bare ops (e.g., `action`, `load`, `LruMap`) likewise import from
|
|
15
|
+
* the specific source file.
|
|
16
|
+
*
|
|
17
|
+
* @internal
|
|
18
|
+
*/
|
|
19
|
+
export { classifyRegistry } from "./build-classify.js";
|
|
20
|
+
export { runCloseCycle } from "./close-cycle.js";
|
|
21
|
+
export { CorrelateCycle } from "./correlate-cycle.js";
|
|
22
|
+
export type { DrainOps } from "./drain.js";
|
|
23
|
+
export { DrainController, type Handle, type HandleBatch, } from "./drain-cycle.js";
|
|
24
|
+
export type { EsOps } from "./event-sourcing.js";
|
|
25
|
+
export { _this_, mergeEventRegister, mergeProjection, registerState, } from "./merge.js";
|
|
26
|
+
export { buildHandle, buildHandleBatch } from "./reactions.js";
|
|
27
|
+
export { SettleLoop } from "./settle.js";
|
|
28
|
+
export { buildDrain, buildEs } from "./tracing.js";
|
|
29
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,eAAe,EACf,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EACL,MAAM,EACN,kBAAkB,EAClB,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { Projection } from "../builders/projection-builder.js";
|
|
2
|
+
import type { State } from "../types/index.js";
|
|
3
|
+
/**
|
|
4
|
+
* Registers a state into a states map and action/event registries,
|
|
5
|
+
* merging with existing same-name states (partial state support).
|
|
6
|
+
*/
|
|
7
|
+
export declare function registerState(state: State<any, any, any>, states: Map<string, State<any, any, any>>, actions: Record<string, any>, events: Record<string, any>): void;
|
|
8
|
+
/**
|
|
9
|
+
* Merges reactions from one event register into another. The target is
|
|
10
|
+
* assumed to already contain entries for every event name in the source
|
|
11
|
+
* (e.g., act-builder's `.withSlice()` registers the slice's states first,
|
|
12
|
+
* which seeds the target events). Reaction names collide by `set()`
|
|
13
|
+
* semantics — last write wins.
|
|
14
|
+
*/
|
|
15
|
+
export declare function mergeEventRegister(target: Record<string, {
|
|
16
|
+
reactions: Map<string, unknown>;
|
|
17
|
+
}>, source: Record<string, {
|
|
18
|
+
reactions: Map<string, unknown>;
|
|
19
|
+
}>): void;
|
|
20
|
+
/**
|
|
21
|
+
* Merges a projection's event schemas and reactions into an event registry,
|
|
22
|
+
* deduplicating reaction names by appending "_p" on collision.
|
|
23
|
+
*/
|
|
24
|
+
export declare function mergeProjection(proj: Projection<any>, events: Record<string, any>): void;
|
|
25
|
+
export declare const _this_: ({ stream }: {
|
|
26
|
+
stream: string;
|
|
27
|
+
}) => {
|
|
28
|
+
source: string;
|
|
29
|
+
target: string;
|
|
30
|
+
};
|
|
31
|
+
//# sourceMappingURL=merge.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../../src/internal/merge.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,KAAK,EAAU,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAuDvD;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,IAAI,CAON;AAwHD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,EAC3D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,GAC1D,IAAI,CAQN;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,IAAI,CAiBN;AAGD,eAAO,MAAM,MAAM,GAAI,YAAY;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE;;;CAGnD,CAAC"}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module reactions
|
|
3
|
+
* @category Internal
|
|
4
|
+
*
|
|
5
|
+
* Reaction dispatch — what runs inside the drain pipeline once `runDrainCycle`
|
|
6
|
+
* has fetched events for a leased stream. Two shapes:
|
|
7
|
+
*
|
|
8
|
+
* - per-event `handle`: walks payloads sequentially, builds a scoped `IAct`
|
|
9
|
+
* that auto-injects `reactingTo` so handlers don't have to thread it
|
|
10
|
+
* through manually
|
|
11
|
+
* - bulk `handleBatch`: hands every event for a static-target projection to
|
|
12
|
+
* a single batch callback, enabling one-transaction replays
|
|
13
|
+
*
|
|
14
|
+
* Both share `_finalize`, which collapses the retry-vs-block decision and
|
|
15
|
+
* the "report error only when nothing was handled" rule.
|
|
16
|
+
*
|
|
17
|
+
* @internal
|
|
18
|
+
*/
|
|
19
|
+
import type { Actor, IAct, Logger, Schemas } from "../types/index.js";
|
|
20
|
+
import type { Handle, HandleBatch } from "./drain-cycle.js";
|
|
21
|
+
/**
|
|
22
|
+
* Dependencies a reaction handler needs from the orchestrator: the logger
|
|
23
|
+
* for retry/error breadcrumbs, plus the bound `IAct` methods that the scoped
|
|
24
|
+
* proxy hands to user reaction code.
|
|
25
|
+
*
|
|
26
|
+
* @internal
|
|
27
|
+
*/
|
|
28
|
+
export type ReactionDeps<TEvents extends Schemas, TActions extends Schemas, TActor extends Actor = Actor> = {
|
|
29
|
+
readonly logger: Logger;
|
|
30
|
+
readonly boundDo: IAct<TEvents, TActions, TActor>["do"];
|
|
31
|
+
readonly boundLoad: IAct<TEvents, TActions, TActor>["load"];
|
|
32
|
+
readonly boundQuery: IAct<TEvents, TActions, TActor>["query"];
|
|
33
|
+
readonly boundQueryArray: IAct<TEvents, TActions, TActor>["query_array"];
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* Builds the per-event reaction dispatcher passed to `runDrainCycle`.
|
|
37
|
+
*
|
|
38
|
+
* The scoped `IAct` proxy auto-injects the triggering event as `reactingTo`
|
|
39
|
+
* when handlers call `do()` without it (#587), keeping the correlation
|
|
40
|
+
* chain by default. The non-do methods are reused across all dispatches —
|
|
41
|
+
* only `do` rebinds per payload because it captures the triggering event.
|
|
42
|
+
*
|
|
43
|
+
* @internal
|
|
44
|
+
*/
|
|
45
|
+
export declare function buildHandle<TEvents extends Schemas, TActions extends Schemas, TActor extends Actor = Actor>(deps: ReactionDeps<TEvents, TActions, TActor>): Handle<TEvents>;
|
|
46
|
+
/**
|
|
47
|
+
* Builds the bulk reaction dispatcher passed to `runDrainCycle`. All events
|
|
48
|
+
* for a static-target projection are handed to a single callback so the
|
|
49
|
+
* projection can do one transaction per drain (catch-up replays especially).
|
|
50
|
+
*
|
|
51
|
+
* @internal
|
|
52
|
+
*/
|
|
53
|
+
export declare function buildHandleBatch<TEvents extends Schemas>(logger: Logger): HandleBatch<TEvents>;
|
|
54
|
+
//# sourceMappingURL=reactions.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"reactions.d.ts","sourceRoot":"","sources":["../../../src/internal/reactions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,KAAK,EAGL,IAAI,EAEJ,MAAM,EAGN,OAAO,EAER,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,CACtB,OAAO,SAAS,OAAO,EACvB,QAAQ,SAAS,OAAO,EACxB,MAAM,SAAS,KAAK,GAAG,KAAK,IAC1B;IACF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5D,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;IAC9D,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC;CAC1E,CAAC;AA6BF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,OAAO,SAAS,OAAO,EACvB,QAAQ,SAAS,OAAO,EACxB,MAAM,SAAS,KAAK,GAAG,KAAK,EAC5B,IAAI,EAAE,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAoDhE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,OAAO,EACtD,MAAM,EAAE,MAAM,GACb,WAAW,CAAC,OAAO,CAAC,CA2BtB"}
|