ihsm 0.0.19 → 0.0.21
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 +273 -132
- package/lib/cjs/index.d.ts +692 -40
- package/lib/cjs/index.js +193 -31
- package/lib/cjs/index.js.map +1 -1
- package/lib/esm/index.d.ts +692 -40
- package/lib/esm/index.js +193 -31
- package/lib/esm/index.js.map +1 -1
- package/package.json +15 -11
package/lib/cjs/index.js
CHANGED
|
@@ -9,103 +9,162 @@ const hsm_1 = require("./internal/hsm");
|
|
|
9
9
|
const utils_1 = require("./internal/utils");
|
|
10
10
|
// export type DispatchErrorCallback<Context, Protocol extends {} | undefined> = (hsm: Hsm<Context, Protocol>, traceWriter: TraceWriter, err: Error) => void;
|
|
11
11
|
/**
|
|
12
|
-
*
|
|
12
|
+
* Controls how much diagnostic detail the runtime emits through {@link TraceWriter}.
|
|
13
|
+
*
|
|
14
|
+
* Set at construction via {@link makeHsm} or mutate {@link Properties.traceLevel} on a
|
|
15
|
+
* live instance. Changing the level swaps the internal dispatch tracer implementation.
|
|
16
|
+
*
|
|
13
17
|
* @category Factory
|
|
14
18
|
*/
|
|
15
19
|
var TraceLevel;
|
|
16
20
|
(function (TraceLevel) {
|
|
21
|
+
/**
|
|
22
|
+
* Production mode: minimal tracing overhead, no verbose dispatch steps.
|
|
23
|
+
* Use in hot paths and shipped bundles when trace output is disabled.
|
|
24
|
+
*/
|
|
17
25
|
TraceLevel[TraceLevel["PRODUCTION"] = 0] = "PRODUCTION";
|
|
26
|
+
/**
|
|
27
|
+
* Debug mode: transition boundaries, handler entry/exit, and error summaries.
|
|
28
|
+
* Default for {@link makeHsm}. Suitable for development and integration tests.
|
|
29
|
+
*/
|
|
18
30
|
TraceLevel[TraceLevel["DEBUG"] = 1] = "DEBUG";
|
|
31
|
+
/**
|
|
32
|
+
* Verbose debug: includes prototype-chain lookup walks, cache hits/misses, and
|
|
33
|
+
* nested trace domains. Use when correlating handler code with tutorial trace panels.
|
|
34
|
+
*/
|
|
19
35
|
TraceLevel[TraceLevel["VERBOSE_DEBUG"] = 2] = "VERBOSE_DEBUG";
|
|
20
36
|
})(TraceLevel || (exports.TraceLevel = TraceLevel = {}));
|
|
21
37
|
/**
|
|
22
|
-
*
|
|
38
|
+
* Abstract root class for every state in the hierarchy.
|
|
39
|
+
*
|
|
40
|
+
* States are **never constructed directly** — the runtime binds one instance object whose
|
|
41
|
+
* prototype moves along the class chain. Subclass `TopState` (or a child state), implement
|
|
42
|
+
* your `Protocol` methods, and pass the root class to {@link makeHsm}.
|
|
43
|
+
*
|
|
44
|
+
* Forwards {@link State} / {@link Properties} APIs and default {@link StateEvents} behavior.
|
|
45
|
+
*
|
|
23
46
|
* @category State machine
|
|
24
47
|
*/
|
|
25
48
|
class TopState {
|
|
49
|
+
/** Domain context (injected by runtime — do not assign in constructors). */
|
|
26
50
|
ctx;
|
|
51
|
+
/** Handler view of the machine (`this` inside methods delegates here for core operations). */
|
|
27
52
|
hsm;
|
|
28
53
|
constructor() {
|
|
29
54
|
throw new Error('Fatal error: States cannot be instantiated');
|
|
30
55
|
}
|
|
56
|
+
/** @inheritdoc Properties.eventName */
|
|
31
57
|
get eventName() {
|
|
32
58
|
return this.hsm.eventName;
|
|
33
59
|
}
|
|
60
|
+
/** @inheritdoc Properties.eventPayload */
|
|
34
61
|
get eventPayload() {
|
|
35
62
|
return this.hsm.eventPayload;
|
|
36
63
|
}
|
|
64
|
+
/** @inheritdoc Properties.traceHeader */
|
|
37
65
|
get traceHeader() {
|
|
38
66
|
return this.hsm.traceHeader;
|
|
39
67
|
}
|
|
68
|
+
/** @inheritdoc Properties.topState */
|
|
40
69
|
get topState() {
|
|
41
70
|
return this.hsm.topState;
|
|
42
71
|
}
|
|
72
|
+
/** @inheritdoc Properties.currentStateName */
|
|
43
73
|
get currentStateName() {
|
|
44
74
|
return this.hsm.currentStateName;
|
|
45
75
|
}
|
|
76
|
+
/** @inheritdoc Properties.currentState */
|
|
46
77
|
get currentState() {
|
|
47
78
|
return this.hsm.currentState;
|
|
48
79
|
}
|
|
80
|
+
/** @inheritdoc Properties.ctxTypeName */
|
|
49
81
|
get ctxTypeName() {
|
|
50
82
|
return this.hsm.ctxTypeName;
|
|
51
83
|
}
|
|
84
|
+
/** @inheritdoc Properties.traceLevel */
|
|
52
85
|
set traceLevel(value) {
|
|
53
86
|
this.hsm.traceLevel = value;
|
|
54
87
|
}
|
|
88
|
+
/** @inheritdoc Properties.traceLevel */
|
|
55
89
|
get traceLevel() {
|
|
56
90
|
return this.hsm.traceLevel;
|
|
57
91
|
}
|
|
92
|
+
/** @inheritdoc Properties.topStateName */
|
|
58
93
|
get topStateName() {
|
|
59
94
|
return this.hsm.topStateName;
|
|
60
95
|
}
|
|
96
|
+
/** @inheritdoc Properties.traceWriter */
|
|
61
97
|
get traceWriter() {
|
|
62
98
|
return this.hsm.traceWriter;
|
|
63
99
|
}
|
|
100
|
+
/** @inheritdoc Properties.traceWriter */
|
|
64
101
|
set traceWriter(value) {
|
|
65
102
|
this.hsm.traceWriter = value;
|
|
66
103
|
}
|
|
104
|
+
/** @inheritdoc Properties.dispatchErrorCallback */
|
|
67
105
|
get dispatchErrorCallback() {
|
|
68
106
|
return this.hsm.dispatchErrorCallback;
|
|
69
107
|
}
|
|
108
|
+
/** @inheritdoc Properties.dispatchErrorCallback */
|
|
70
109
|
set dispatchErrorCallback(value) {
|
|
71
110
|
this.hsm.dispatchErrorCallback = value;
|
|
72
111
|
}
|
|
112
|
+
/** @inheritdoc State.transition */
|
|
73
113
|
transition(nextState) {
|
|
74
114
|
this.hsm.transition(nextState);
|
|
75
115
|
}
|
|
116
|
+
/** @inheritdoc State.unhandled */
|
|
76
117
|
unhandled() {
|
|
77
118
|
this.hsm.unhandled();
|
|
78
119
|
}
|
|
120
|
+
/** @inheritdoc State.sleep */
|
|
79
121
|
sleep(millis) {
|
|
80
122
|
return this.hsm.sleep(millis);
|
|
81
123
|
}
|
|
124
|
+
/** @inheritdoc Base.post */
|
|
82
125
|
post(eventName, ...eventPayload) {
|
|
83
126
|
this.hsm.post(eventName, ...eventPayload);
|
|
84
127
|
}
|
|
128
|
+
/** @inheritdoc Base.deferredPost */
|
|
85
129
|
deferredPost(millis, eventName, ...eventPayload) {
|
|
86
130
|
this.hsm.deferredPost(millis, eventName, ...eventPayload);
|
|
87
131
|
}
|
|
132
|
+
/** @inheritdoc State.postNow */
|
|
88
133
|
postNow(eventName, ...eventPayload) {
|
|
89
134
|
this.hsm.postNow(eventName, ...eventPayload);
|
|
90
135
|
}
|
|
136
|
+
/** @inheritdoc StateEvents.onExit */
|
|
91
137
|
onExit() { }
|
|
138
|
+
/** @inheritdoc StateEvents.onEntry */
|
|
92
139
|
onEntry() { }
|
|
140
|
+
/** @inheritdoc StateEvents.onError */
|
|
93
141
|
onError(error) {
|
|
94
142
|
throw error;
|
|
95
143
|
}
|
|
144
|
+
/** @inheritdoc StateEvents.onUnhandled */
|
|
96
145
|
onUnhandled(error) {
|
|
97
146
|
throw error;
|
|
98
147
|
}
|
|
99
148
|
}
|
|
100
149
|
exports.TopState = TopState;
|
|
101
150
|
/**
|
|
151
|
+
* Base class for all ihsm runtime errors carrying machine context.
|
|
152
|
+
*
|
|
153
|
+
* @typeParam Context - Domain context at failure time
|
|
154
|
+
* @typeParam Protocol - Vocabulary type (for typed subclasses)
|
|
155
|
+
*
|
|
102
156
|
* @category Error
|
|
103
157
|
*/
|
|
104
158
|
class HsmError extends Error {
|
|
159
|
+
/** Discriminator matching the class name (`EventHandlerError`, etc.). */
|
|
105
160
|
name;
|
|
161
|
+
/** {@link Properties.topStateName} when the error was constructed. */
|
|
106
162
|
topStateName;
|
|
163
|
+
/** {@link Properties.currentStateName} when the error was constructed. */
|
|
107
164
|
stateName;
|
|
165
|
+
/** Snapshot of {@link State.ctx} when the error was constructed. */
|
|
108
166
|
context;
|
|
167
|
+
/** Original thrown value when this error wraps a handler or lifecycle failure. */
|
|
109
168
|
cause;
|
|
110
169
|
constructor(name, hsm, message, cause) {
|
|
111
170
|
super(message);
|
|
@@ -118,10 +177,18 @@ class HsmError extends Error {
|
|
|
118
177
|
}
|
|
119
178
|
exports.HsmError = HsmError;
|
|
120
179
|
/**
|
|
180
|
+
* Error base for failures during **event dispatch**, with correlated event metadata.
|
|
181
|
+
*
|
|
182
|
+
* @typeParam Context - Domain context
|
|
183
|
+
* @typeParam Protocol - Vocabulary interface
|
|
184
|
+
* @typeParam EventName - Event or service key being processed
|
|
185
|
+
*
|
|
121
186
|
* @category Error
|
|
122
187
|
*/
|
|
123
188
|
class RuntimeError extends HsmError {
|
|
189
|
+
/** Event or service name that was active when the failure occurred. */
|
|
124
190
|
eventName;
|
|
191
|
+
/** Client-supplied arguments (excluding resolve/reject for services). */
|
|
125
192
|
eventPayload;
|
|
126
193
|
constructor(errorName, hsm, message, cause) {
|
|
127
194
|
super(errorName, hsm, message, cause);
|
|
@@ -131,6 +198,8 @@ class RuntimeError extends HsmError {
|
|
|
131
198
|
}
|
|
132
199
|
exports.RuntimeError = RuntimeError;
|
|
133
200
|
/**
|
|
201
|
+
* Thrown when {@link StateEvents.onExit} or {@link StateEvents.onEntry} throws during a transition.
|
|
202
|
+
*
|
|
134
203
|
* @category Error
|
|
135
204
|
*/
|
|
136
205
|
class TransitionError extends RuntimeError {
|
|
@@ -138,6 +207,14 @@ class TransitionError extends RuntimeError {
|
|
|
138
207
|
failedCallback;
|
|
139
208
|
fromStateName;
|
|
140
209
|
toStateName;
|
|
210
|
+
/**
|
|
211
|
+
* @param hsm - Machine view at failure time
|
|
212
|
+
* @param cause - Error thrown from the lifecycle hook
|
|
213
|
+
* @param failedStateName - Display name of the state whose hook failed
|
|
214
|
+
* @param failedCallback - Which hook failed (`onExit` or `onEntry`)
|
|
215
|
+
* @param fromStateName - Leaf state before the transition
|
|
216
|
+
* @param toStateName - Requested destination state
|
|
217
|
+
*/
|
|
141
218
|
constructor(hsm, cause, failedStateName, failedCallback, fromStateName, toStateName) {
|
|
142
219
|
super('TransitionError', hsm, `${failedStateName}.${failedCallback}() has failed while executing a transition from ${fromStateName} to ${toStateName}`, cause);
|
|
143
220
|
this.failedStateName = failedStateName;
|
|
@@ -148,28 +225,41 @@ class TransitionError extends RuntimeError {
|
|
|
148
225
|
}
|
|
149
226
|
exports.TransitionError = TransitionError;
|
|
150
227
|
/**
|
|
228
|
+
* Thrown when an event handler body throws and {@link StateEvents.onError} does not recover.
|
|
229
|
+
*
|
|
151
230
|
* @category Error
|
|
152
231
|
*/
|
|
153
232
|
class EventHandlerError extends RuntimeError {
|
|
233
|
+
/**
|
|
234
|
+
* @param hsm - Machine view with {@link eventName} set to the failing handler
|
|
235
|
+
* @param cause - Error thrown from handler code
|
|
236
|
+
*/
|
|
154
237
|
constructor(hsm, cause) {
|
|
155
238
|
super('EventHandlerError', hsm, `an error was thrown while executing event handler #${hsm.eventName} in state ${hsm.currentStateName}`, cause);
|
|
156
239
|
}
|
|
157
240
|
}
|
|
158
241
|
exports.EventHandlerError = EventHandlerError;
|
|
159
242
|
/**
|
|
243
|
+
* Thrown when no handler matches the dispatched event and {@link StateEvents.onUnhandled} rethrows.
|
|
244
|
+
*
|
|
160
245
|
* @category Error
|
|
161
246
|
*/
|
|
162
247
|
class UnhandledEventError extends RuntimeError {
|
|
248
|
+
/** @param hsm - Machine view with the unmatched {@link eventName} */
|
|
163
249
|
constructor(hsm) {
|
|
164
250
|
super('UnhandledEventError', hsm, `event #${hsm.eventName} was unhandled in state ${hsm.currentStateName}`);
|
|
165
251
|
}
|
|
166
252
|
}
|
|
167
253
|
exports.UnhandledEventError = UnhandledEventError;
|
|
168
254
|
/**
|
|
255
|
+
* Thrown at **class definition** time when {@link InitialState} is applied twice to one parent.
|
|
256
|
+
*
|
|
169
257
|
* @category Error
|
|
170
258
|
*/
|
|
171
259
|
class InitialStateError extends Error {
|
|
260
|
+
/** Display name of the state passed to the duplicate {@link InitialState} call. */
|
|
172
261
|
targetStateName;
|
|
262
|
+
/** @param targetState - The state class whose parent already has an initial substate */
|
|
173
263
|
constructor(targetState) {
|
|
174
264
|
super(`State '${(0, utils_1.getStateName)(Object.getPrototypeOf(targetState.prototype).constructor)}' must not have more than one initial state`);
|
|
175
265
|
this.name = 'InitialStateError';
|
|
@@ -178,19 +268,32 @@ class InitialStateError extends Error {
|
|
|
178
268
|
}
|
|
179
269
|
exports.InitialStateError = InitialStateError;
|
|
180
270
|
/**
|
|
271
|
+
* Thrown when {@link StateEvents.onError} itself throws, leaving the machine unrecoverable.
|
|
272
|
+
*
|
|
181
273
|
* @category Error
|
|
182
274
|
*/
|
|
183
275
|
class FatalError extends RuntimeError {
|
|
276
|
+
/**
|
|
277
|
+
* @param hsm - Machine view at failure time
|
|
278
|
+
* @param cause - Error thrown from `onError`
|
|
279
|
+
*/
|
|
184
280
|
constructor(hsm, cause) {
|
|
185
281
|
super('FatalError', hsm, `onError() has thrown ${(0, utils_1.quoteError)(cause)}`, cause);
|
|
186
282
|
}
|
|
187
283
|
}
|
|
188
284
|
exports.FatalError = FatalError;
|
|
189
285
|
/**
|
|
286
|
+
* Thrown when {@link StateEvents.onEntry} fails during the initial `@InitialState` walk at startup.
|
|
287
|
+
*
|
|
190
288
|
* @category Error
|
|
191
289
|
*/
|
|
192
290
|
class InitializationError extends HsmError {
|
|
193
291
|
failedState;
|
|
292
|
+
/**
|
|
293
|
+
* @param hsm - Partially initialized machine
|
|
294
|
+
* @param failedState - State class whose `onEntry` threw
|
|
295
|
+
* @param cause - Original error from `onEntry`
|
|
296
|
+
*/
|
|
194
297
|
constructor(hsm, failedState, cause) {
|
|
195
298
|
super('InitializationError', hsm, `state ${(0, utils_1.getStateName)(failedState)} has thrown ${(0, utils_1.quoteError)(cause)} during initialization`, cause);
|
|
196
299
|
this.failedState = failedState;
|
|
@@ -198,7 +301,11 @@ class InitializationError extends HsmError {
|
|
|
198
301
|
}
|
|
199
302
|
exports.InitializationError = InitializationError;
|
|
200
303
|
/**
|
|
201
|
-
* Terminal
|
|
304
|
+
* Terminal sink state class used when the runtime cannot recover from an error.
|
|
305
|
+
*
|
|
306
|
+
* Assign or transition here from custom {@link StateEvents.onError} handlers when you need a
|
|
307
|
+
* well-defined quiescent state. Display name is pre-registered as `'FatalErrorState'`.
|
|
308
|
+
*
|
|
202
309
|
* @category State machine
|
|
203
310
|
*/
|
|
204
311
|
class FatalErrorState extends TopState {
|
|
@@ -207,8 +314,28 @@ exports.FatalErrorState = FatalErrorState;
|
|
|
207
314
|
(0, utils_1.defineStateName)(TopState, 'TopState');
|
|
208
315
|
(0, utils_1.defineStateName)(FatalErrorState, 'FatalErrorState');
|
|
209
316
|
/**
|
|
210
|
-
*
|
|
211
|
-
*
|
|
317
|
+
* Declares `TargetState` as the **initial substate** of its direct parent composite.
|
|
318
|
+
*
|
|
319
|
+
* Apply as a TypeScript decorator or call as a function at class definition time. Exactly **one**
|
|
320
|
+
* initial child is allowed per parent; a second mark throws {@link InitialStateError}.
|
|
321
|
+
*
|
|
322
|
+
* @typeParam Context - Domain context type
|
|
323
|
+
* @typeParam Protocol - Vocabulary interface
|
|
324
|
+
* @param TargetState - Child state class whose **parent** is `Object.getPrototypeOf(TargetState.prototype).constructor`
|
|
325
|
+
*
|
|
326
|
+
* @throws {@link InitialStateError} when the parent already has an initial substate
|
|
327
|
+
*
|
|
328
|
+
* @remarks
|
|
329
|
+
* During {@link makeHsm} initialization, the runtime descends `@InitialState` chains from the
|
|
330
|
+
* root until the deepest initial leaf is active, running {@link StateEvents.onEntry} along the path.
|
|
331
|
+
*
|
|
332
|
+
* @example
|
|
333
|
+
* ```ts
|
|
334
|
+
* class Composite extends TopState {}
|
|
335
|
+
*
|
|
336
|
+
* @InitialState
|
|
337
|
+
* class Idle extends Composite {}
|
|
338
|
+
* ```
|
|
212
339
|
*/
|
|
213
340
|
function InitialState(TargetState) {
|
|
214
341
|
const ParentOfTargetState = Object.getPrototypeOf(TargetState.prototype).constructor;
|
|
@@ -228,50 +355,56 @@ function InitialState(TargetState) {
|
|
|
228
355
|
});
|
|
229
356
|
}
|
|
230
357
|
/**
|
|
231
|
-
* Assigns a stable display name to a state class.
|
|
358
|
+
* Assigns a stable **display name** to a single state class.
|
|
359
|
+
*
|
|
360
|
+
* Minifiers rewrite `Class.name` in production browser bundles; explicit registration keeps
|
|
361
|
+
* {@link Properties.currentStateName}, trace output, and error messages readable everywhere.
|
|
232
362
|
*
|
|
233
|
-
*
|
|
234
|
-
*
|
|
235
|
-
*
|
|
236
|
-
*
|
|
237
|
-
* every environment (Node and minified browsers alike).
|
|
363
|
+
* @typeParam Context - Domain context type
|
|
364
|
+
* @typeParam Protocol - Vocabulary interface
|
|
365
|
+
* @param state - State class constructor to tag
|
|
366
|
+
* @param name - Non-empty display string used in traces and errors (not required to match `Class.name`)
|
|
238
367
|
*
|
|
239
|
-
*
|
|
240
|
-
* never
|
|
368
|
+
* @remarks
|
|
369
|
+
* Stored as a non-enumerable own property — never inherited by subclasses from the prototype chain.
|
|
370
|
+
* {@link registerStateNames} is preferred when every state is a named export from one module.
|
|
241
371
|
*
|
|
242
372
|
* @example
|
|
243
373
|
* ```ts
|
|
244
374
|
* class Door extends TopState {}
|
|
245
375
|
* defineStateName(Door, 'Door');
|
|
246
376
|
* ```
|
|
377
|
+
*
|
|
247
378
|
* @category State machine
|
|
248
379
|
*/
|
|
249
380
|
function defineStateName(state, name) {
|
|
250
381
|
(0, utils_1.defineStateName)(state, name);
|
|
251
382
|
}
|
|
252
383
|
/**
|
|
253
|
-
* Registers
|
|
254
|
-
* using the export key as the display name.
|
|
384
|
+
* Registers display names for **every** state class in an exports object, using each **export key** as the name.
|
|
255
385
|
*
|
|
256
|
-
*
|
|
257
|
-
*
|
|
258
|
-
* each state class gets its export key as its display name. Non state-class
|
|
259
|
-
* values (factory functions, interfaces compiled away, constants) are ignored.
|
|
386
|
+
* @param exports - Module namespace (`import * as machine`) or object literal of state classes.
|
|
387
|
+
* Non-constructor exports (constants, functions, types) are silently skipped
|
|
260
388
|
*
|
|
261
|
-
* @
|
|
389
|
+
* @remarks
|
|
390
|
+
* Export keys survive minification even when class identifiers are mangled — this is the recommended
|
|
391
|
+
* approach for browser bundles without `keep_classnames`. Call once at module load after all state
|
|
392
|
+
* classes are defined.
|
|
393
|
+
*
|
|
394
|
+
* @example Single module
|
|
262
395
|
* ```ts
|
|
263
|
-
* // machine.ts
|
|
264
396
|
* export class DoorTop extends TopState {}
|
|
265
397
|
* export class Open extends DoorTop {}
|
|
266
398
|
* export class Closed extends DoorTop {}
|
|
267
399
|
* registerStateNames({ DoorTop, Open, Closed });
|
|
268
400
|
* ```
|
|
269
|
-
*
|
|
401
|
+
*
|
|
402
|
+
* @example Re-exporting namespace
|
|
270
403
|
* ```ts
|
|
271
|
-
* // from another module
|
|
272
404
|
* import * as machine from './machine';
|
|
273
405
|
* registerStateNames(machine);
|
|
274
406
|
* ```
|
|
407
|
+
*
|
|
275
408
|
* @category State machine
|
|
276
409
|
*/
|
|
277
410
|
function registerStateNames(exports) {
|
|
@@ -309,14 +442,43 @@ const defaultTraceWriter = new ConsoleTraceWriter();
|
|
|
309
442
|
const defaultTraceLevel = TraceLevel.DEBUG;
|
|
310
443
|
const defaultInitialize = true;
|
|
311
444
|
/**
|
|
312
|
-
* Creates a state machine
|
|
313
|
-
*
|
|
314
|
-
* @
|
|
315
|
-
*
|
|
316
|
-
*
|
|
317
|
-
* @
|
|
318
|
-
* @
|
|
319
|
-
* @param
|
|
445
|
+
* Creates and optionally initializes a hierarchical state machine **actor** bound to `ctx`.
|
|
446
|
+
*
|
|
447
|
+
* The returned {@link Hsm} is the single runtime object: external clients call `post` / `call` /
|
|
448
|
+
* `sync`; the active state is the instance prototype chain updated by {@link State.transition}.
|
|
449
|
+
*
|
|
450
|
+
* @typeParam Context - Domain context type (inferred from `ctx` when passed inline)
|
|
451
|
+
* @typeParam Protocol - Event/service vocabulary (inferred from `topState` when it implements `Protocol`)
|
|
452
|
+
* @param topState - Root state **class** constructor (must extend {@link TopState})
|
|
453
|
+
* @param ctx - Mutable domain object shared by all states; stored on the instance as {@link Hsm.ctx}
|
|
454
|
+
* @param initialize - When `true` (default), enqueue the initial walk: descend `@InitialState`
|
|
455
|
+
* chains from `topState` and run {@link StateEvents.onEntry} on each entered state until the
|
|
456
|
+
* initial leaf is active. When `false`, prototype starts at `topState` with **no** entry hooks
|
|
457
|
+
* @param traceLevel - Initial {@link TraceLevel} (default {@link TraceLevel.DEBUG})
|
|
458
|
+
* @param traceWriter - {@link TraceWriter} implementation (default: prefixes strings with state name and logs to `console`)
|
|
459
|
+
* @param dispatchErrorCallback - Last-resort error hook (default: trace + rethrow)
|
|
460
|
+
* @returns Client handle implementing {@link Hsm} for the same `Context` and `Protocol`
|
|
461
|
+
*
|
|
462
|
+
* @remarks
|
|
463
|
+
* - Await {@link Hsm.sync} after creation when `initialize: true` before asserting initial state
|
|
464
|
+
* - Zero runtime npm dependencies; safe to embed in browsers when state names are registered
|
|
465
|
+
* - Transition LCA paths are cached per machine instance for the lifetime of the actor
|
|
466
|
+
*
|
|
467
|
+
* @example Minimal door machine
|
|
468
|
+
* ```ts
|
|
469
|
+
* const door = makeHsm(DoorTop, { openCount: 0 });
|
|
470
|
+
* await door.sync();
|
|
471
|
+
* door.post('open');
|
|
472
|
+
* await door.sync();
|
|
473
|
+
* ```
|
|
474
|
+
*
|
|
475
|
+
* @example Custom tracing in tests
|
|
476
|
+
* ```ts
|
|
477
|
+
* const writer = { write: (_hsm, msg) => logs.push(msg) };
|
|
478
|
+
* const sm = makeHsm(Top, ctx, true, TraceLevel.VERBOSE_DEBUG, writer);
|
|
479
|
+
* await sm.sync();
|
|
480
|
+
* ```
|
|
481
|
+
*
|
|
320
482
|
* @category Factory
|
|
321
483
|
*/
|
|
322
484
|
function makeHsm(topState, ctx, initialize = defaultInitialize, traceLevel = defaultTraceLevel, traceWriter = defaultTraceWriter, dispatchErrorCallback = defaultDispatchErrorCallback) {
|
package/lib/cjs/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
|