ihsm 0.0.19 → 0.0.20
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 +13 -11
package/lib/esm/index.js
CHANGED
|
@@ -2,102 +2,161 @@ import { HsmObject } from './internal/hsm.js';
|
|
|
2
2
|
import { hasInitialState, quoteError, defineStateName as defineStateNameInternal, getStateName } from './internal/utils.js';
|
|
3
3
|
// export type DispatchErrorCallback<Context, Protocol extends {} | undefined> = (hsm: Hsm<Context, Protocol>, traceWriter: TraceWriter, err: Error) => void;
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
5
|
+
* Controls how much diagnostic detail the runtime emits through {@link TraceWriter}.
|
|
6
|
+
*
|
|
7
|
+
* Set at construction via {@link makeHsm} or mutate {@link Properties.traceLevel} on a
|
|
8
|
+
* live instance. Changing the level swaps the internal dispatch tracer implementation.
|
|
9
|
+
*
|
|
6
10
|
* @category Factory
|
|
7
11
|
*/
|
|
8
12
|
export var TraceLevel;
|
|
9
13
|
(function (TraceLevel) {
|
|
14
|
+
/**
|
|
15
|
+
* Production mode: minimal tracing overhead, no verbose dispatch steps.
|
|
16
|
+
* Use in hot paths and shipped bundles when trace output is disabled.
|
|
17
|
+
*/
|
|
10
18
|
TraceLevel[TraceLevel["PRODUCTION"] = 0] = "PRODUCTION";
|
|
19
|
+
/**
|
|
20
|
+
* Debug mode: transition boundaries, handler entry/exit, and error summaries.
|
|
21
|
+
* Default for {@link makeHsm}. Suitable for development and integration tests.
|
|
22
|
+
*/
|
|
11
23
|
TraceLevel[TraceLevel["DEBUG"] = 1] = "DEBUG";
|
|
24
|
+
/**
|
|
25
|
+
* Verbose debug: includes prototype-chain lookup walks, cache hits/misses, and
|
|
26
|
+
* nested trace domains. Use when correlating handler code with tutorial trace panels.
|
|
27
|
+
*/
|
|
12
28
|
TraceLevel[TraceLevel["VERBOSE_DEBUG"] = 2] = "VERBOSE_DEBUG";
|
|
13
29
|
})(TraceLevel || (TraceLevel = {}));
|
|
14
30
|
/**
|
|
15
|
-
*
|
|
31
|
+
* Abstract root class for every state in the hierarchy.
|
|
32
|
+
*
|
|
33
|
+
* States are **never constructed directly** — the runtime binds one instance object whose
|
|
34
|
+
* prototype moves along the class chain. Subclass `TopState` (or a child state), implement
|
|
35
|
+
* your `Protocol` methods, and pass the root class to {@link makeHsm}.
|
|
36
|
+
*
|
|
37
|
+
* Forwards {@link State} / {@link Properties} APIs and default {@link StateEvents} behavior.
|
|
38
|
+
*
|
|
16
39
|
* @category State machine
|
|
17
40
|
*/
|
|
18
41
|
export class TopState {
|
|
42
|
+
/** Domain context (injected by runtime — do not assign in constructors). */
|
|
19
43
|
ctx;
|
|
44
|
+
/** Handler view of the machine (`this` inside methods delegates here for core operations). */
|
|
20
45
|
hsm;
|
|
21
46
|
constructor() {
|
|
22
47
|
throw new Error('Fatal error: States cannot be instantiated');
|
|
23
48
|
}
|
|
49
|
+
/** @inheritdoc Properties.eventName */
|
|
24
50
|
get eventName() {
|
|
25
51
|
return this.hsm.eventName;
|
|
26
52
|
}
|
|
53
|
+
/** @inheritdoc Properties.eventPayload */
|
|
27
54
|
get eventPayload() {
|
|
28
55
|
return this.hsm.eventPayload;
|
|
29
56
|
}
|
|
57
|
+
/** @inheritdoc Properties.traceHeader */
|
|
30
58
|
get traceHeader() {
|
|
31
59
|
return this.hsm.traceHeader;
|
|
32
60
|
}
|
|
61
|
+
/** @inheritdoc Properties.topState */
|
|
33
62
|
get topState() {
|
|
34
63
|
return this.hsm.topState;
|
|
35
64
|
}
|
|
65
|
+
/** @inheritdoc Properties.currentStateName */
|
|
36
66
|
get currentStateName() {
|
|
37
67
|
return this.hsm.currentStateName;
|
|
38
68
|
}
|
|
69
|
+
/** @inheritdoc Properties.currentState */
|
|
39
70
|
get currentState() {
|
|
40
71
|
return this.hsm.currentState;
|
|
41
72
|
}
|
|
73
|
+
/** @inheritdoc Properties.ctxTypeName */
|
|
42
74
|
get ctxTypeName() {
|
|
43
75
|
return this.hsm.ctxTypeName;
|
|
44
76
|
}
|
|
77
|
+
/** @inheritdoc Properties.traceLevel */
|
|
45
78
|
set traceLevel(value) {
|
|
46
79
|
this.hsm.traceLevel = value;
|
|
47
80
|
}
|
|
81
|
+
/** @inheritdoc Properties.traceLevel */
|
|
48
82
|
get traceLevel() {
|
|
49
83
|
return this.hsm.traceLevel;
|
|
50
84
|
}
|
|
85
|
+
/** @inheritdoc Properties.topStateName */
|
|
51
86
|
get topStateName() {
|
|
52
87
|
return this.hsm.topStateName;
|
|
53
88
|
}
|
|
89
|
+
/** @inheritdoc Properties.traceWriter */
|
|
54
90
|
get traceWriter() {
|
|
55
91
|
return this.hsm.traceWriter;
|
|
56
92
|
}
|
|
93
|
+
/** @inheritdoc Properties.traceWriter */
|
|
57
94
|
set traceWriter(value) {
|
|
58
95
|
this.hsm.traceWriter = value;
|
|
59
96
|
}
|
|
97
|
+
/** @inheritdoc Properties.dispatchErrorCallback */
|
|
60
98
|
get dispatchErrorCallback() {
|
|
61
99
|
return this.hsm.dispatchErrorCallback;
|
|
62
100
|
}
|
|
101
|
+
/** @inheritdoc Properties.dispatchErrorCallback */
|
|
63
102
|
set dispatchErrorCallback(value) {
|
|
64
103
|
this.hsm.dispatchErrorCallback = value;
|
|
65
104
|
}
|
|
105
|
+
/** @inheritdoc State.transition */
|
|
66
106
|
transition(nextState) {
|
|
67
107
|
this.hsm.transition(nextState);
|
|
68
108
|
}
|
|
109
|
+
/** @inheritdoc State.unhandled */
|
|
69
110
|
unhandled() {
|
|
70
111
|
this.hsm.unhandled();
|
|
71
112
|
}
|
|
113
|
+
/** @inheritdoc State.sleep */
|
|
72
114
|
sleep(millis) {
|
|
73
115
|
return this.hsm.sleep(millis);
|
|
74
116
|
}
|
|
117
|
+
/** @inheritdoc Base.post */
|
|
75
118
|
post(eventName, ...eventPayload) {
|
|
76
119
|
this.hsm.post(eventName, ...eventPayload);
|
|
77
120
|
}
|
|
121
|
+
/** @inheritdoc Base.deferredPost */
|
|
78
122
|
deferredPost(millis, eventName, ...eventPayload) {
|
|
79
123
|
this.hsm.deferredPost(millis, eventName, ...eventPayload);
|
|
80
124
|
}
|
|
125
|
+
/** @inheritdoc State.postNow */
|
|
81
126
|
postNow(eventName, ...eventPayload) {
|
|
82
127
|
this.hsm.postNow(eventName, ...eventPayload);
|
|
83
128
|
}
|
|
129
|
+
/** @inheritdoc StateEvents.onExit */
|
|
84
130
|
onExit() { }
|
|
131
|
+
/** @inheritdoc StateEvents.onEntry */
|
|
85
132
|
onEntry() { }
|
|
133
|
+
/** @inheritdoc StateEvents.onError */
|
|
86
134
|
onError(error) {
|
|
87
135
|
throw error;
|
|
88
136
|
}
|
|
137
|
+
/** @inheritdoc StateEvents.onUnhandled */
|
|
89
138
|
onUnhandled(error) {
|
|
90
139
|
throw error;
|
|
91
140
|
}
|
|
92
141
|
}
|
|
93
142
|
/**
|
|
143
|
+
* Base class for all ihsm runtime errors carrying machine context.
|
|
144
|
+
*
|
|
145
|
+
* @typeParam Context - Domain context at failure time
|
|
146
|
+
* @typeParam Protocol - Vocabulary type (for typed subclasses)
|
|
147
|
+
*
|
|
94
148
|
* @category Error
|
|
95
149
|
*/
|
|
96
150
|
export class HsmError extends Error {
|
|
151
|
+
/** Discriminator matching the class name (`EventHandlerError`, etc.). */
|
|
97
152
|
name;
|
|
153
|
+
/** {@link Properties.topStateName} when the error was constructed. */
|
|
98
154
|
topStateName;
|
|
155
|
+
/** {@link Properties.currentStateName} when the error was constructed. */
|
|
99
156
|
stateName;
|
|
157
|
+
/** Snapshot of {@link State.ctx} when the error was constructed. */
|
|
100
158
|
context;
|
|
159
|
+
/** Original thrown value when this error wraps a handler or lifecycle failure. */
|
|
101
160
|
cause;
|
|
102
161
|
constructor(name, hsm, message, cause) {
|
|
103
162
|
super(message);
|
|
@@ -109,10 +168,18 @@ export class HsmError extends Error {
|
|
|
109
168
|
}
|
|
110
169
|
}
|
|
111
170
|
/**
|
|
171
|
+
* Error base for failures during **event dispatch**, with correlated event metadata.
|
|
172
|
+
*
|
|
173
|
+
* @typeParam Context - Domain context
|
|
174
|
+
* @typeParam Protocol - Vocabulary interface
|
|
175
|
+
* @typeParam EventName - Event or service key being processed
|
|
176
|
+
*
|
|
112
177
|
* @category Error
|
|
113
178
|
*/
|
|
114
179
|
export class RuntimeError extends HsmError {
|
|
180
|
+
/** Event or service name that was active when the failure occurred. */
|
|
115
181
|
eventName;
|
|
182
|
+
/** Client-supplied arguments (excluding resolve/reject for services). */
|
|
116
183
|
eventPayload;
|
|
117
184
|
constructor(errorName, hsm, message, cause) {
|
|
118
185
|
super(errorName, hsm, message, cause);
|
|
@@ -121,6 +188,8 @@ export class RuntimeError extends HsmError {
|
|
|
121
188
|
}
|
|
122
189
|
}
|
|
123
190
|
/**
|
|
191
|
+
* Thrown when {@link StateEvents.onExit} or {@link StateEvents.onEntry} throws during a transition.
|
|
192
|
+
*
|
|
124
193
|
* @category Error
|
|
125
194
|
*/
|
|
126
195
|
export class TransitionError extends RuntimeError {
|
|
@@ -128,6 +197,14 @@ export class TransitionError extends RuntimeError {
|
|
|
128
197
|
failedCallback;
|
|
129
198
|
fromStateName;
|
|
130
199
|
toStateName;
|
|
200
|
+
/**
|
|
201
|
+
* @param hsm - Machine view at failure time
|
|
202
|
+
* @param cause - Error thrown from the lifecycle hook
|
|
203
|
+
* @param failedStateName - Display name of the state whose hook failed
|
|
204
|
+
* @param failedCallback - Which hook failed (`onExit` or `onEntry`)
|
|
205
|
+
* @param fromStateName - Leaf state before the transition
|
|
206
|
+
* @param toStateName - Requested destination state
|
|
207
|
+
*/
|
|
131
208
|
constructor(hsm, cause, failedStateName, failedCallback, fromStateName, toStateName) {
|
|
132
209
|
super('TransitionError', hsm, `${failedStateName}.${failedCallback}() has failed while executing a transition from ${fromStateName} to ${toStateName}`, cause);
|
|
133
210
|
this.failedStateName = failedStateName;
|
|
@@ -137,26 +214,39 @@ export class TransitionError extends RuntimeError {
|
|
|
137
214
|
}
|
|
138
215
|
}
|
|
139
216
|
/**
|
|
217
|
+
* Thrown when an event handler body throws and {@link StateEvents.onError} does not recover.
|
|
218
|
+
*
|
|
140
219
|
* @category Error
|
|
141
220
|
*/
|
|
142
221
|
export class EventHandlerError extends RuntimeError {
|
|
222
|
+
/**
|
|
223
|
+
* @param hsm - Machine view with {@link eventName} set to the failing handler
|
|
224
|
+
* @param cause - Error thrown from handler code
|
|
225
|
+
*/
|
|
143
226
|
constructor(hsm, cause) {
|
|
144
227
|
super('EventHandlerError', hsm, `an error was thrown while executing event handler #${hsm.eventName} in state ${hsm.currentStateName}`, cause);
|
|
145
228
|
}
|
|
146
229
|
}
|
|
147
230
|
/**
|
|
231
|
+
* Thrown when no handler matches the dispatched event and {@link StateEvents.onUnhandled} rethrows.
|
|
232
|
+
*
|
|
148
233
|
* @category Error
|
|
149
234
|
*/
|
|
150
235
|
export class UnhandledEventError extends RuntimeError {
|
|
236
|
+
/** @param hsm - Machine view with the unmatched {@link eventName} */
|
|
151
237
|
constructor(hsm) {
|
|
152
238
|
super('UnhandledEventError', hsm, `event #${hsm.eventName} was unhandled in state ${hsm.currentStateName}`);
|
|
153
239
|
}
|
|
154
240
|
}
|
|
155
241
|
/**
|
|
242
|
+
* Thrown at **class definition** time when {@link InitialState} is applied twice to one parent.
|
|
243
|
+
*
|
|
156
244
|
* @category Error
|
|
157
245
|
*/
|
|
158
246
|
export class InitialStateError extends Error {
|
|
247
|
+
/** Display name of the state passed to the duplicate {@link InitialState} call. */
|
|
159
248
|
targetStateName;
|
|
249
|
+
/** @param targetState - The state class whose parent already has an initial substate */
|
|
160
250
|
constructor(targetState) {
|
|
161
251
|
super(`State '${getStateName(Object.getPrototypeOf(targetState.prototype).constructor)}' must not have more than one initial state`);
|
|
162
252
|
this.name = 'InitialStateError';
|
|
@@ -164,25 +254,42 @@ export class InitialStateError extends Error {
|
|
|
164
254
|
}
|
|
165
255
|
}
|
|
166
256
|
/**
|
|
257
|
+
* Thrown when {@link StateEvents.onError} itself throws, leaving the machine unrecoverable.
|
|
258
|
+
*
|
|
167
259
|
* @category Error
|
|
168
260
|
*/
|
|
169
261
|
export class FatalError extends RuntimeError {
|
|
262
|
+
/**
|
|
263
|
+
* @param hsm - Machine view at failure time
|
|
264
|
+
* @param cause - Error thrown from `onError`
|
|
265
|
+
*/
|
|
170
266
|
constructor(hsm, cause) {
|
|
171
267
|
super('FatalError', hsm, `onError() has thrown ${quoteError(cause)}`, cause);
|
|
172
268
|
}
|
|
173
269
|
}
|
|
174
270
|
/**
|
|
271
|
+
* Thrown when {@link StateEvents.onEntry} fails during the initial `@InitialState` walk at startup.
|
|
272
|
+
*
|
|
175
273
|
* @category Error
|
|
176
274
|
*/
|
|
177
275
|
export class InitializationError extends HsmError {
|
|
178
276
|
failedState;
|
|
277
|
+
/**
|
|
278
|
+
* @param hsm - Partially initialized machine
|
|
279
|
+
* @param failedState - State class whose `onEntry` threw
|
|
280
|
+
* @param cause - Original error from `onEntry`
|
|
281
|
+
*/
|
|
179
282
|
constructor(hsm, failedState, cause) {
|
|
180
283
|
super('InitializationError', hsm, `state ${getStateName(failedState)} has thrown ${quoteError(cause)} during initialization`, cause);
|
|
181
284
|
this.failedState = failedState;
|
|
182
285
|
}
|
|
183
286
|
}
|
|
184
287
|
/**
|
|
185
|
-
* Terminal
|
|
288
|
+
* Terminal sink state class used when the runtime cannot recover from an error.
|
|
289
|
+
*
|
|
290
|
+
* Assign or transition here from custom {@link StateEvents.onError} handlers when you need a
|
|
291
|
+
* well-defined quiescent state. Display name is pre-registered as `'FatalErrorState'`.
|
|
292
|
+
*
|
|
186
293
|
* @category State machine
|
|
187
294
|
*/
|
|
188
295
|
export class FatalErrorState extends TopState {
|
|
@@ -190,8 +297,28 @@ export class FatalErrorState extends TopState {
|
|
|
190
297
|
defineStateNameInternal(TopState, 'TopState');
|
|
191
298
|
defineStateNameInternal(FatalErrorState, 'FatalErrorState');
|
|
192
299
|
/**
|
|
193
|
-
*
|
|
194
|
-
*
|
|
300
|
+
* Declares `TargetState` as the **initial substate** of its direct parent composite.
|
|
301
|
+
*
|
|
302
|
+
* Apply as a TypeScript decorator or call as a function at class definition time. Exactly **one**
|
|
303
|
+
* initial child is allowed per parent; a second mark throws {@link InitialStateError}.
|
|
304
|
+
*
|
|
305
|
+
* @typeParam Context - Domain context type
|
|
306
|
+
* @typeParam Protocol - Vocabulary interface
|
|
307
|
+
* @param TargetState - Child state class whose **parent** is `Object.getPrototypeOf(TargetState.prototype).constructor`
|
|
308
|
+
*
|
|
309
|
+
* @throws {@link InitialStateError} when the parent already has an initial substate
|
|
310
|
+
*
|
|
311
|
+
* @remarks
|
|
312
|
+
* During {@link makeHsm} initialization, the runtime descends `@InitialState` chains from the
|
|
313
|
+
* root until the deepest initial leaf is active, running {@link StateEvents.onEntry} along the path.
|
|
314
|
+
*
|
|
315
|
+
* @example
|
|
316
|
+
* ```ts
|
|
317
|
+
* class Composite extends TopState {}
|
|
318
|
+
*
|
|
319
|
+
* @InitialState
|
|
320
|
+
* class Idle extends Composite {}
|
|
321
|
+
* ```
|
|
195
322
|
*/
|
|
196
323
|
export function InitialState(TargetState) {
|
|
197
324
|
const ParentOfTargetState = Object.getPrototypeOf(TargetState.prototype).constructor;
|
|
@@ -211,50 +338,56 @@ export function InitialState(TargetState) {
|
|
|
211
338
|
});
|
|
212
339
|
}
|
|
213
340
|
/**
|
|
214
|
-
* Assigns a stable display name to a state class.
|
|
341
|
+
* Assigns a stable **display name** to a single state class.
|
|
342
|
+
*
|
|
343
|
+
* Minifiers rewrite `Class.name` in production browser bundles; explicit registration keeps
|
|
344
|
+
* {@link Properties.currentStateName}, trace output, and error messages readable everywhere.
|
|
215
345
|
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
*
|
|
220
|
-
* every environment (Node and minified browsers alike).
|
|
346
|
+
* @typeParam Context - Domain context type
|
|
347
|
+
* @typeParam Protocol - Vocabulary interface
|
|
348
|
+
* @param state - State class constructor to tag
|
|
349
|
+
* @param name - Non-empty display string used in traces and errors (not required to match `Class.name`)
|
|
221
350
|
*
|
|
222
|
-
*
|
|
223
|
-
* never
|
|
351
|
+
* @remarks
|
|
352
|
+
* Stored as a non-enumerable own property — never inherited by subclasses from the prototype chain.
|
|
353
|
+
* {@link registerStateNames} is preferred when every state is a named export from one module.
|
|
224
354
|
*
|
|
225
355
|
* @example
|
|
226
356
|
* ```ts
|
|
227
357
|
* class Door extends TopState {}
|
|
228
358
|
* defineStateName(Door, 'Door');
|
|
229
359
|
* ```
|
|
360
|
+
*
|
|
230
361
|
* @category State machine
|
|
231
362
|
*/
|
|
232
363
|
export function defineStateName(state, name) {
|
|
233
364
|
defineStateNameInternal(state, name);
|
|
234
365
|
}
|
|
235
366
|
/**
|
|
236
|
-
* Registers
|
|
237
|
-
* using the export key as the display name.
|
|
367
|
+
* Registers display names for **every** state class in an exports object, using each **export key** as the name.
|
|
238
368
|
*
|
|
239
|
-
*
|
|
240
|
-
*
|
|
241
|
-
* each state class gets its export key as its display name. Non state-class
|
|
242
|
-
* values (factory functions, interfaces compiled away, constants) are ignored.
|
|
369
|
+
* @param exports - Module namespace (`import * as machine`) or object literal of state classes.
|
|
370
|
+
* Non-constructor exports (constants, functions, types) are silently skipped
|
|
243
371
|
*
|
|
244
|
-
* @
|
|
372
|
+
* @remarks
|
|
373
|
+
* Export keys survive minification even when class identifiers are mangled — this is the recommended
|
|
374
|
+
* approach for browser bundles without `keep_classnames`. Call once at module load after all state
|
|
375
|
+
* classes are defined.
|
|
376
|
+
*
|
|
377
|
+
* @example Single module
|
|
245
378
|
* ```ts
|
|
246
|
-
* // machine.ts
|
|
247
379
|
* export class DoorTop extends TopState {}
|
|
248
380
|
* export class Open extends DoorTop {}
|
|
249
381
|
* export class Closed extends DoorTop {}
|
|
250
382
|
* registerStateNames({ DoorTop, Open, Closed });
|
|
251
383
|
* ```
|
|
252
|
-
*
|
|
384
|
+
*
|
|
385
|
+
* @example Re-exporting namespace
|
|
253
386
|
* ```ts
|
|
254
|
-
* // from another module
|
|
255
387
|
* import * as machine from './machine';
|
|
256
388
|
* registerStateNames(machine);
|
|
257
389
|
* ```
|
|
390
|
+
*
|
|
258
391
|
* @category State machine
|
|
259
392
|
*/
|
|
260
393
|
export function registerStateNames(exports) {
|
|
@@ -292,14 +425,43 @@ const defaultTraceWriter = new ConsoleTraceWriter();
|
|
|
292
425
|
const defaultTraceLevel = TraceLevel.DEBUG;
|
|
293
426
|
const defaultInitialize = true;
|
|
294
427
|
/**
|
|
295
|
-
* Creates a state machine
|
|
296
|
-
*
|
|
297
|
-
* @
|
|
298
|
-
*
|
|
299
|
-
*
|
|
300
|
-
* @
|
|
301
|
-
* @
|
|
302
|
-
* @param
|
|
428
|
+
* Creates and optionally initializes a hierarchical state machine **actor** bound to `ctx`.
|
|
429
|
+
*
|
|
430
|
+
* The returned {@link Hsm} is the single runtime object: external clients call `post` / `call` /
|
|
431
|
+
* `sync`; the active state is the instance prototype chain updated by {@link State.transition}.
|
|
432
|
+
*
|
|
433
|
+
* @typeParam Context - Domain context type (inferred from `ctx` when passed inline)
|
|
434
|
+
* @typeParam Protocol - Event/service vocabulary (inferred from `topState` when it implements `Protocol`)
|
|
435
|
+
* @param topState - Root state **class** constructor (must extend {@link TopState})
|
|
436
|
+
* @param ctx - Mutable domain object shared by all states; stored on the instance as {@link Hsm.ctx}
|
|
437
|
+
* @param initialize - When `true` (default), enqueue the initial walk: descend `@InitialState`
|
|
438
|
+
* chains from `topState` and run {@link StateEvents.onEntry} on each entered state until the
|
|
439
|
+
* initial leaf is active. When `false`, prototype starts at `topState` with **no** entry hooks
|
|
440
|
+
* @param traceLevel - Initial {@link TraceLevel} (default {@link TraceLevel.DEBUG})
|
|
441
|
+
* @param traceWriter - {@link TraceWriter} implementation (default: prefixes strings with state name and logs to `console`)
|
|
442
|
+
* @param dispatchErrorCallback - Last-resort error hook (default: trace + rethrow)
|
|
443
|
+
* @returns Client handle implementing {@link Hsm} for the same `Context` and `Protocol`
|
|
444
|
+
*
|
|
445
|
+
* @remarks
|
|
446
|
+
* - Await {@link Hsm.sync} after creation when `initialize: true` before asserting initial state
|
|
447
|
+
* - Zero runtime npm dependencies; safe to embed in browsers when state names are registered
|
|
448
|
+
* - Transition LCA paths are cached per machine instance for the lifetime of the actor
|
|
449
|
+
*
|
|
450
|
+
* @example Minimal door machine
|
|
451
|
+
* ```ts
|
|
452
|
+
* const door = makeHsm(DoorTop, { openCount: 0 });
|
|
453
|
+
* await door.sync();
|
|
454
|
+
* door.post('open');
|
|
455
|
+
* await door.sync();
|
|
456
|
+
* ```
|
|
457
|
+
*
|
|
458
|
+
* @example Custom tracing in tests
|
|
459
|
+
* ```ts
|
|
460
|
+
* const writer = { write: (_hsm, msg) => logs.push(msg) };
|
|
461
|
+
* const sm = makeHsm(Top, ctx, true, TraceLevel.VERBOSE_DEBUG, writer);
|
|
462
|
+
* await sm.sync();
|
|
463
|
+
* ```
|
|
464
|
+
*
|
|
303
465
|
* @category Factory
|
|
304
466
|
*/
|
|
305
467
|
export function makeHsm(topState, ctx, initialize = defaultInitialize, traceLevel = defaultTraceLevel, traceWriter = defaultTraceWriter, dispatchErrorCallback = defaultDispatchErrorCallback) {
|
package/lib/esm/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,eAAe,IAAI,uBAAuB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,eAAe,IAAI,uBAAuB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA2EzH,6JAA6J;AAE7J;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,UAgBX;AAhBD,WAAY,UAAU;IACrB;;;OAGG;IACH,uDAAU,CAAA;IACV;;;OAGG;IACH,6CAAK,CAAA;IACL;;;OAGG;IACH,6DAAa,CAAA;AACd,CAAC,EAhBW,UAAU,KAAV,UAAU,QAgBrB;AAujBD;;;;;;;;;;GAUG;AACH,MAAM,OAAgB,QAAQ;IAC7B,4EAA4E;IACnE,GAAG,CAAW;IACvB,8FAA8F;IACrF,GAAG,CAA4B;IACxC;QACC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAC/D,CAAC;IACD,uCAAuC;IACvC,IAAI,SAAS;QACZ,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;IAC3B,CAAC;IACD,0CAA0C;IAC1C,IAAI,YAAY;QACf,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC;IAC9B,CAAC;IACD,yCAAyC;IACzC,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC;IAC7B,CAAC;IACD,sCAAsC;IACtC,IAAI,QAAQ;QACX,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;IAC1B,CAAC;IACD,8CAA8C;IAC9C,IAAI,gBAAgB;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAClC,CAAC;IACD,0CAA0C;IAC1C,IAAI,YAAY;QACf,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC;IAC9B,CAAC;IACD,yCAAyC;IACzC,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC;IAC7B,CAAC;IACD,wCAAwC;IACxC,IAAI,UAAU,CAAC,KAAiB;QAC/B,IAAI,CAAC,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC;IAC7B,CAAC;IACD,wCAAwC;IACxC,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC;IAC5B,CAAC;IACD,0CAA0C;IAC1C,IAAI,YAAY;QACf,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC;IAC9B,CAAC;IACD,yCAAyC;IACzC,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC;IAC7B,CAAC;IACD,yCAAyC;IACzC,IAAI,WAAW,CAAC,KAAK;QACpB,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED,mDAAmD;IACnD,IAAI,qBAAqB;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,qBAAqB,CAAC;IACvC,CAAC;IACD,mDAAmD;IACnD,IAAI,qBAAqB,CAAC,KAAK;QAC9B,IAAI,CAAC,GAAG,CAAC,qBAAqB,GAAG,KAAK,CAAC;IACxC,CAAC;IACD,mCAAmC;IACnC,UAAU,CAAC,SAAwC;QAClD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IACD,kCAAkC;IAClC,SAAS;QACR,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;IACtB,CAAC;IACD,8BAA8B;IAC9B,KAAK,CAAC,MAAc;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,4BAA4B;IAC5B,IAAI,CAAmC,SAA2C,EAAE,GAAG,YAA+C;QACrI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,YAAY,CAAC,CAAC;IAC3C,CAAC;IACD,oCAAoC;IACpC,YAAY,CAAmC,MAAc,EAAE,SAA2C,EAAE,GAAG,YAA+C;QAC7J,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,YAAY,CAAC,CAAC;IAC3D,CAAC;IACD,gCAAgC;IAChC,OAAO,CAAmC,SAA2C,EAAE,GAAG,YAA+C;QACxI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,YAAY,CAAC,CAAC;IAC9C,CAAC;IAED,qCAAqC;IACrC,MAAM,KAA0B,CAAC;IAEjC,sCAAsC;IACtC,OAAO,KAA0B,CAAC;IAElC,sCAAsC;IACtC,OAAO,CAAmC,KAAiD;QAC1F,MAAM,KAAK,CAAC;IACb,CAAC;IAED,0CAA0C;IAC1C,WAAW,CAAmC,KAAwD;QACrG,MAAM,KAAK,CAAC;IACb,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAgB,QAAmD,SAAQ,KAAK;IACrF,yEAAyE;IACzE,IAAI,CAAS;IACb,sEAAsE;IACtE,YAAY,CAAS;IACrB,0EAA0E;IAC1E,SAAS,CAAS;IAClB,oEAAoE;IACpE,OAAO,CAAU;IACjB,kFAAkF;IAClF,KAAK,CAAS;IAEd,YAAsB,IAAY,EAAE,GAA6B,EAAE,OAAe,EAAE,KAAa;QAChG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,gBAAgB,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD;AAED;;;;;;;;GAQG;AACH,MAAM,OAAgB,YAAyF,SAAQ,QAA2B;IACjJ,uEAAuE;IACvE,SAAS,CAAmC;IAC5C,yEAAyE;IACzE,YAAY,CAAoC;IAEhD,YAAsB,SAAiB,EAAE,GAA6B,EAAE,OAAe,EAAE,KAAa;QACrG,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,SAA6C,CAAC;QACnE,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC,YAAiD,CAAC;IAC3E,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,OAAO,eAA4F,SAAQ,YAA0C;IAYlJ;IACA;IACA;IACA;IAdR;;;;;;;OAOG;IACH,YACC,GAA6B,EAC7B,KAAY,EACL,eAAuB,EACvB,cAAoC,EACpC,aAAqB,EACrB,WAAmB;QAE1B,KAAK,CAAC,iBAAiB,EAAE,GAAG,EAAE,GAAG,eAAe,IAAI,cAAc,mDAAmD,aAAa,OAAO,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;QALxJ,oBAAe,GAAf,eAAe,CAAQ;QACvB,mBAAc,GAAd,cAAc,CAAsB;QACpC,kBAAa,GAAb,aAAa,CAAQ;QACrB,gBAAW,GAAX,WAAW,CAAQ;IAG3B,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAA8F,SAAQ,YAA0C;IAC5J;;;OAGG;IACH,YAAY,GAA6B,EAAE,KAAY;QACtD,KAAK,CAAC,mBAAmB,EAAE,GAAG,EAAE,sDAAsD,GAAG,CAAC,SAAS,aAAa,GAAG,CAAC,gBAAgB,EAAE,EAAE,KAAK,CAAC,CAAC;IAChJ,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,OAAO,mBAAgG,SAAQ,YAA0C;IAC9J,qEAAqE;IACrE,YAAY,GAA6B;QACxC,KAAK,CAAC,qBAAqB,EAAE,GAAG,EAAE,UAAU,GAAG,CAAC,SAAS,2BAA2B,GAAG,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC7G,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAA4D,SAAQ,KAAK;IACrF,mFAAmF;IACnF,eAAe,CAAS;IAExB,wFAAwF;IACxF,YAAY,WAA0C;QACrD,KAAK,CAAC,UAAU,YAAY,CAAC,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,WAA4C,CAAC,6CAA6C,CAAC,CAAC;QACtK,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,eAAe,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IAClD,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,OAAO,UAAuF,SAAQ,YAA0C;IACrJ;;;OAGG;IACH,YAAY,GAA6B,EAAE,KAAY;QACtD,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,wBAAwB,UAAU,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAC9E,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,OAAO,mBAA8D,SAAQ,QAA2B;IAQrG;IAPR;;;;OAIG;IACH,YACC,GAA6B,EACtB,WAA0C,EACjD,KAAY;QAEZ,KAAK,CAAC,qBAAqB,EAAE,GAAG,EAAE,SAAS,YAAY,CAAC,WAAW,CAAC,eAAe,UAAU,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;QAH9H,gBAAW,GAAX,WAAW,CAA+B;IAIlD,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,eAA0D,SAAQ,QAA2B;CAAG;AAE7G,uBAAuB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC9C,uBAAuB,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAA2C,WAA0C;IAChH,MAAM,mBAAmB,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,WAAW,CAAC;IACrF,IAAI,eAAe,CAAC,mBAAmB,CAAC;QAAE,MAAM,IAAI,iBAAiB,CAAC,WAAW,CAAC,CAAC;IACnF,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,iBAAiB,EAAE;QACrD,KAAK,EAAE,IAAI;QACX,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,KAAK;QACnB,UAAU,EAAE,KAAK;KACjB,CAAC,CAAC;IACH,MAAM,CAAC,cAAc,CAAC,mBAAmB,EAAE,eAAe,EAAE;QAC3D,KAAK,EAAE,WAAW;QAClB,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,KAAK;QACnB,UAAU,EAAE,KAAK;KACjB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,eAAe,CAA2C,KAAoC,EAAE,IAAY;IAC3H,uBAAuB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgC;IAClE,KAAK,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3D,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,uBAAuB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QAC5C,CAAC;IACF,CAAC;AACF,CAAC;AAED,iGAAiG;AACjG,SAAS,YAAY,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,SAAS,GAAI,KAAkB,CAAC,SAAS,CAAC;IAChD,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,IAAI,QAAQ,CAAC,SAAS,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;AAC3G,CAAC;AAED,gBAAgB;AAChB,MAAM,kBAAkB;IACvB,KAAK,CAA2C,GAAkC,EAAE,OAAY;QAC/F,IAAI,OAAO,OAAO,IAAI,QAAQ,EAAE,CAAC;YAChC,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,gBAAgB,KAAK,OAAO,EAAE,CAAC,CAAC;QACtE,CAAC;aAAM,CAAC;YACP,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtB,CAAC;IACF,CAAC;CACD;AAED,SAAS,4BAA4B,CAA2C,GAA4B,EAAE,GAAU;IACvH,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC;IAC/B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,uCAAuC,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC;IAC1G,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACvB,MAAM,GAAG,CAAC;AACX,CAAC;AAED,MAAM,kBAAkB,GAAG,IAAI,kBAAkB,EAAE,CAAC;AACpD,MAAM,iBAAiB,GAAG,UAAU,CAAC,KAAK,CAAC;AAC3C,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,OAAO,CAA2C,QAAuC,EAAE,GAAY,EAAE,aAAsB,iBAAiB,EAAE,aAAyB,iBAAiB,EAAE,cAA2B,kBAAkB,EAAE,wBAAkE,4BAA4B;IAC1V,MAAM,QAAQ,GAAgC;QAC7C,GAAG,EAAE,SAAyD;QAC9D,GAAG,EAAE,GAAG;KACR,CAAC;IACF,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IACpD,QAAQ,CAAC,GAAG,GAAG,IAAI,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,qBAAqB,EAAE,UAAU,CAAC,CAAC;IAC7G,OAAO,QAAQ,CAAC,GAAG,CAAC;AACrB,CAAC"}
|
package/package.json
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
"contributors": [
|
|
8
8
|
"Roberto Boati"
|
|
9
9
|
],
|
|
10
|
-
"description": "
|
|
10
|
+
"description": "Class-based hierarchical state machines and actor mailboxes for TypeScript — typed post/call, zero dependencies",
|
|
11
11
|
"files": [
|
|
12
12
|
"lib"
|
|
13
13
|
],
|
|
@@ -29,6 +29,8 @@
|
|
|
29
29
|
"playwright": "^1.52.0",
|
|
30
30
|
"prettier": "^3.8.3",
|
|
31
31
|
"ts-node": "^10.9.2",
|
|
32
|
+
"typedoc": "^0.28.19",
|
|
33
|
+
"typedoc-plugin-markdown": "^4.11.0",
|
|
32
34
|
"typescript": "^6.0.3",
|
|
33
35
|
"typescript-eslint": "^8.60.0"
|
|
34
36
|
},
|
|
@@ -83,7 +85,7 @@
|
|
|
83
85
|
"build-cjs": "tsc -b tsconfig.lib.json",
|
|
84
86
|
"build-esm": "tsc -b tsconfig.esm.json",
|
|
85
87
|
"build": "tsc -b tsconfig.lib.json tsconfig.esm.json && node scripts/finalize-build.mjs",
|
|
86
|
-
"clean": "rm -rf ./lib ./.tsc ./.nyc_output ./coverage ./docs-build website/.docusaurus website/docs website/sidebars.ts",
|
|
88
|
+
"clean": "rm -rf ./lib ./.tsc ./.nyc_output ./coverage ./docs-build ./.typedoc-out website/.docusaurus website/docs website/sidebars.ts",
|
|
87
89
|
"coverage": "nyc report --reporter=text-lcov",
|
|
88
90
|
"dist": "npm run build && npm run doc",
|
|
89
91
|
"doc": "npm run sync:docs && npm run build -w ihsm-site",
|
|
@@ -92,25 +94,25 @@
|
|
|
92
94
|
"doc:site": "npm run sync:docs && npm run build -w ihsm-site",
|
|
93
95
|
"verify:doc": "bash scripts/verify-docs-site.sh docs-build",
|
|
94
96
|
"verify:source": "bash scripts/verify-no-generated-in-source.sh",
|
|
95
|
-
"lint": "npm run typecheck && eslint --max-warnings 0 'src/**/*.ts' '
|
|
97
|
+
"lint": "npm run typecheck && eslint --max-warnings 0 'src/**/*.ts' 'examples/**/*.ts' && prettier --check 'src/**/*.ts' 'examples/**/*.ts' 'website/**/*.{ts,tsx}'",
|
|
96
98
|
"predist": "npm run clean",
|
|
97
|
-
"prettier": "prettier --write 'src/**/*.ts' '
|
|
99
|
+
"prettier": "prettier --write 'src/**/*.ts' 'examples/**/*.ts' 'website/**/*.{ts,tsx}'",
|
|
98
100
|
"release:check": "npm run test:all && npm run lint && npm run build && npm run doc && npm run verify:doc",
|
|
99
101
|
"prepublishOnly": "npm run test:all && npm run build",
|
|
100
102
|
"test:node": "TS_NODE_PROJECT=tsconfig.lib.json nyc mocha",
|
|
101
103
|
"test:browser": "node scripts/run-browser-tests.mjs",
|
|
102
104
|
"test:browser:unit": "node scripts/run-browser-tests.mjs --suite unit",
|
|
103
|
-
"test:browser:
|
|
105
|
+
"test:browser:examples": "node scripts/run-browser-tests.mjs --suite examples",
|
|
104
106
|
"test": "npm run test:node && npm run test:browser",
|
|
105
|
-
"test:
|
|
106
|
-
"test:
|
|
107
|
-
"test:
|
|
108
|
-
"test:all": "npm test && npm run test:
|
|
107
|
+
"test:examples:node": "TS_NODE_PROJECT=tsconfig.examples.json mocha --config .mocharc.examples.json",
|
|
108
|
+
"test:examples:browser": "node scripts/run-browser-tests.mjs --suite examples",
|
|
109
|
+
"test:examples": "npm run test:examples:node && npm run test:examples:browser",
|
|
110
|
+
"test:all": "npm test && npm run test:examples",
|
|
109
111
|
"typecheck": "tsc -b",
|
|
110
|
-
"prepare:types": "tsc -b tsconfig.lib.json tsconfig.
|
|
112
|
+
"prepare:types": "tsc -b tsconfig.lib.json tsconfig.examples.json",
|
|
111
113
|
"prepare:ide": "npm run sync:docs && npm run prepare:types",
|
|
112
114
|
"pretypecheck": "npm run prepare:ide"
|
|
113
115
|
},
|
|
114
116
|
"types": "./lib/cjs/index.d.ts",
|
|
115
|
-
"version": "0.0.
|
|
117
|
+
"version": "0.0.20"
|
|
116
118
|
}
|