@flighthq/statechart 0.5.1-next.973.788d3d7 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/README.md +2 -2
  2. package/dist/.tsbuildinfo.contract +1 -0
  3. package/dist/.tsbuildinfo.runtime +1 -0
  4. package/dist/contract.d.ts +7 -4
  5. package/dist/contract.d.ts.map +1 -1
  6. package/dist/contract.js +8 -4
  7. package/dist/contract.js.map +1 -1
  8. package/dist/contract.statechart-types.d.ts +3 -0
  9. package/dist/contract.statechart-types.d.ts.map +1 -0
  10. package/dist/contract.statechart-types.js +4 -0
  11. package/dist/contract.statechart-types.js.map +1 -0
  12. package/dist/enableStatechartGuards.d.ts +5 -4
  13. package/dist/enableStatechartGuards.d.ts.map +1 -1
  14. package/dist/enableStatechartGuards.js +11 -4
  15. package/dist/enableStatechartGuards.js.map +1 -1
  16. package/dist/index.d.ts +3 -3
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +4 -3
  19. package/dist/index.js.map +1 -1
  20. package/dist/statechart.d.ts +13 -12
  21. package/dist/statechart.d.ts.map +1 -1
  22. package/dist/statechart.js +302 -263
  23. package/dist/statechart.js.map +1 -1
  24. package/dist/statechartCompat.d.ts +46 -0
  25. package/dist/statechartCompat.d.ts.map +1 -0
  26. package/dist/statechartCompat.js +127 -0
  27. package/dist/statechartCompat.js.map +1 -0
  28. package/dist/statechartInstanceFields.d.ts +3 -0
  29. package/dist/statechartInstanceFields.d.ts.map +1 -0
  30. package/dist/statechartInstanceFields.js +13 -0
  31. package/dist/statechartInstanceFields.js.map +1 -0
  32. package/dist/statechartInstanceInit.d.ts +4 -0
  33. package/dist/statechartInstanceInit.d.ts.map +1 -0
  34. package/dist/statechartInstanceInit.js +7 -0
  35. package/dist/statechartInstanceInit.js.map +1 -0
  36. package/dist/statechartRuntime.d.ts +9 -0
  37. package/dist/statechartRuntime.d.ts.map +1 -0
  38. package/dist/statechartRuntime.js +25 -0
  39. package/dist/statechartRuntime.js.map +1 -0
  40. package/dist/statechartSignalEmit.d.ts +3 -0
  41. package/dist/statechartSignalEmit.d.ts.map +1 -0
  42. package/dist/statechartSignalEmit.js +7 -0
  43. package/dist/statechartSignalEmit.js.map +1 -0
  44. package/dist/statechartSignals.d.ts +4 -3
  45. package/dist/statechartSignals.d.ts.map +1 -1
  46. package/dist/statechartSignals.js +2 -2
  47. package/dist/statechartSignals.js.map +1 -1
  48. package/dist/statechartTypedArrays.d.ts +4 -0
  49. package/dist/statechartTypedArrays.d.ts.map +1 -0
  50. package/dist/statechartTypedArrays.js +10 -0
  51. package/dist/statechartTypedArrays.js.map +1 -0
  52. package/dist/types.d.ts +85 -0
  53. package/dist/types.d.ts.map +1 -0
  54. package/dist/types.js +33 -0
  55. package/dist/types.js.map +1 -0
  56. package/package.json +7 -6
  57. package/src/enableStatechartGuards.test.ts +26 -17
  58. package/src/statechart.test.ts +434 -291
  59. package/src/statechartCompat.test.ts +165 -0
  60. package/src/statechartInstanceFields.test.ts +36 -0
  61. package/src/statechartInstanceInit.test.ts +20 -0
  62. package/src/statechartIntegerDomain.test.ts +57 -0
  63. package/src/statechartRuntime.test.ts +55 -0
  64. package/src/statechartSignalEmit.test.ts +19 -0
  65. package/src/statechartSignals.test.ts +9 -9
  66. package/src/statechartTypedArrays.test.ts +25 -0
@@ -1,13 +1,11 @@
1
+ // Generated from crates/flight-statechart/tests/statechart_test.rs by flight-compiler.
2
+ // Rust is authoritative; run `npm run generate` after changing it.
3
+
4
+ import { describe, expect, it } from 'vitest';
5
+
1
6
  import {
2
7
  StatechartAtomicStateKind,
3
- StatechartComparison,
4
- StatechartInputKind,
5
8
  StatechartNestedStateKind,
6
- StatechartTransitionStatus,
7
- } from '@flighthq/types/contract';
8
- import type { Statechart, StatechartCondition, StatechartTransition } from '@flighthq/types/contract';
9
-
10
- import {
11
9
  advanceStatechartInstance,
12
10
  createStatechartInstance,
13
11
  explainStatechartTransition,
@@ -15,427 +13,572 @@ import {
15
13
  getStatechartInputIndex,
16
14
  getStatechartRegionBlend,
17
15
  getStatechartRegionState,
18
- initializeStatechartInstance,
19
16
  setStatechartBooleanInput,
20
17
  setStatechartNumberInput,
21
18
  setStatechartRegionDuration,
22
- } from './statechart';
19
+ } from './contract.ts';
20
+ import type {
21
+ StatechartComparison,
22
+ StatechartCondition,
23
+ StatechartInput,
24
+ StatechartInstanceRaw,
25
+ StatechartRaw,
26
+ StatechartRegion,
27
+ StatechartState,
28
+ StatechartTransition,
29
+ StatechartTransitionExplanation,
30
+ } from './contract.ts';
31
+
32
+ function createInstance(chart: Readonly<StatechartRaw>): StatechartInstanceRaw {
33
+ const chartRef = chart;
34
+ return createStatechartInstance(chartRef);
35
+ }
36
+
37
+ function condition(inputIndex: number, comparison: StatechartComparison, value: number): StatechartCondition {
38
+ return { comparison: comparison, inputIndex: inputIndex, value: value };
39
+ }
40
+
41
+ function createEmptyChart(): StatechartRaw {
42
+ return {
43
+ inputs: [],
44
+ name: undefined,
45
+ regions: [
46
+ {
47
+ initialStateIndex: 0,
48
+ name: undefined,
49
+ states: [{ kind: String(StatechartAtomicStateKind), name: undefined, transitions: [] }],
50
+ },
51
+ ],
52
+ };
53
+ }
54
+
55
+ function createSingleTransitionChart(
56
+ inputs: StatechartInput[],
57
+ conditions: StatechartCondition[],
58
+ durationMs: number,
59
+ exitTimeRatio: number,
60
+ ): StatechartRaw {
61
+ return {
62
+ inputs: inputs,
63
+ name: undefined,
64
+ regions: [
65
+ {
66
+ initialStateIndex: 0,
67
+ name: undefined,
68
+ states: [
69
+ {
70
+ kind: String(StatechartAtomicStateKind),
71
+ name: undefined,
72
+ transitions: [transition(1, conditions, durationMs, exitTimeRatio)],
73
+ },
74
+ { kind: String(StatechartAtomicStateKind), name: undefined, transitions: [] },
75
+ ],
76
+ },
77
+ ],
78
+ };
79
+ }
80
+
81
+ function createTwoRegionTriggerChart(): StatechartRaw {
82
+ const triggerTransition = transition(1, [condition(0, 'GreaterThan', 999.0)], 0.0, -1.0);
83
+ return {
84
+ inputs: [{ initialValue: 0.0, kind: 'Trigger', name: 'go' }],
85
+ name: undefined,
86
+ regions: [createTriggerRegion(triggerTransition), createTriggerRegion(triggerTransition)],
87
+ };
88
+ }
89
+
90
+ function createTriggerRegion(transition: StatechartTransition): StatechartRegion {
91
+ return {
92
+ initialStateIndex: 0,
93
+ name: undefined,
94
+ states: [
95
+ { kind: String(StatechartAtomicStateKind), name: undefined, transitions: [transition] },
96
+ { kind: String(StatechartAtomicStateKind), name: undefined, transitions: [] },
97
+ ],
98
+ };
99
+ }
100
+
101
+ function transition(
102
+ targetStateIndex: number,
103
+ conditions: StatechartCondition[],
104
+ durationMs: number,
105
+ exitTimeRatio: number,
106
+ ): StatechartTransition {
107
+ return {
108
+ conditions: conditions,
109
+ durationMs: durationMs,
110
+ exitTimeRatio: exitTimeRatio,
111
+ targetStateIndex: targetStateIndex,
112
+ };
113
+ }
23
114
 
24
115
  describe('advanceStatechartInstance', () => {
25
116
  it('advances every concurrent region before clearing a shared trigger', () => {
26
117
  const chart = createTwoRegionTriggerChart();
27
- const instance = createStatechartInstance(chart);
28
-
118
+ const instance = createInstance(chart);
29
119
  fireStatechartTrigger(instance, 0);
30
- expect(advanceStatechartInstance(instance, 0)).toBe(2);
31
- expect([...instance.regionStates]).toEqual([1, 1]);
32
- expect(instance.inputValues[0]).toBe(0);
120
+ expect(advanceStatechartInstance(instance, 0.0)).toEqual(2);
121
+ expect(instance!.regionStates.length).toEqual(2);
122
+ expect(instance!.regionStates[0]).toEqual(1);
123
+ expect(instance!.regionStates[1]).toEqual(1);
124
+ expect(instance!.inputValues[0]).toEqual(0.0);
33
125
  });
34
-
35
- it('requires all data-only conditions and selects the first eligible transition', () => {
36
- const chart: Statechart = {
126
+ it('requires all data only conditions and selects the first eligible transition', () => {
127
+ const chart: StatechartRaw = {
37
128
  inputs: [
38
- { initialValue: 0, kind: StatechartInputKind.Boolean, name: 'armed' },
39
- { initialValue: 2, kind: StatechartInputKind.Number, name: 'speed' },
129
+ { initialValue: 0.0, kind: 'Boolean', name: 'armed' },
130
+ { initialValue: 2.0, kind: 'Number', name: 'speed' },
40
131
  ],
132
+ name: undefined,
41
133
  regions: [
42
134
  {
43
135
  initialStateIndex: 0,
136
+ name: undefined,
44
137
  states: [
45
138
  {
46
- kind: StatechartAtomicStateKind,
139
+ kind: String(StatechartAtomicStateKind),
140
+ name: undefined,
47
141
  transitions: [
48
- transition(1, [condition(0, StatechartComparison.Equal, 1)]),
49
- transition(2, [
50
- condition(0, StatechartComparison.Equal, 0),
51
- condition(1, StatechartComparison.GreaterThan, 4),
52
- ]),
53
- transition(1, [
54
- condition(0, StatechartComparison.Equal, 0),
55
- condition(1, StatechartComparison.LessThanOrEqual, 2),
56
- ]),
142
+ transition(1, [condition(0, 'Equal', 1.0)], 0.0, -1.0),
143
+ transition(2, [condition(0, 'Equal', 0.0), condition(1, 'GreaterThan', 4.0)], 0.0, -1.0),
144
+ transition(1, [condition(0, 'Equal', 0.0), condition(1, 'LessThanOrEqual', 2.0)], 0.0, -1.0),
57
145
  ],
58
146
  },
59
- { kind: StatechartAtomicStateKind, transitions: [] },
60
- { kind: StatechartAtomicStateKind, transitions: [] },
147
+ { kind: String(StatechartAtomicStateKind), name: undefined, transitions: [] },
148
+ { kind: String(StatechartAtomicStateKind), name: undefined, transitions: [] },
61
149
  ],
62
150
  },
63
151
  ],
64
- };
65
- const instance = createStatechartInstance(chart);
66
-
67
- expect(advanceStatechartInstance(instance, 0)).toBe(1);
68
- expect(instance.regionStates[0]).toBe(1);
152
+ } as const;
153
+ const instance = createInstance(chart);
154
+ expect(advanceStatechartInstance(instance, 0.0)).toEqual(1);
155
+ expect(instance!.regionStates[0]).toEqual(1);
69
156
  });
70
-
71
- it.each([
72
- [StatechartComparison.Equal, 3, 3, true],
73
- [StatechartComparison.GreaterThan, 3, 2, true],
74
- [StatechartComparison.GreaterThanOrEqual, 3, 3, true],
75
- [StatechartComparison.LessThan, 3, 4, true],
76
- [StatechartComparison.LessThanOrEqual, 3, 3, true],
77
- [StatechartComparison.NotEqual, 3, 4, true],
78
- ])('evaluates the %s numeric comparison', (comparison, inputValue, expectedValue, expected) => {
157
+ it('evaluates equal numeric comparison', () => {
79
158
  const chart = createSingleTransitionChart(
80
- [{ initialValue: inputValue, kind: StatechartInputKind.Number }],
81
- [condition(0, comparison, expectedValue)],
159
+ [{ initialValue: 3.0, kind: 'Number', name: undefined }],
160
+ [condition(0, 'Equal', 3.0)],
161
+ 0.0,
162
+ -1.0,
82
163
  );
83
- expect(advanceStatechartInstance(createStatechartInstance(chart), 0) === 1).toBe(expected);
164
+ expect(advanceStatechartInstance(createInstance(chart), 0.0) === 1).toEqual(true);
165
+ });
166
+ it('evaluates greater than numeric comparison', () => {
167
+ const chart = createSingleTransitionChart(
168
+ [{ initialValue: 3.0, kind: 'Number', name: undefined }],
169
+ [condition(0, 'GreaterThan', 2.0)],
170
+ 0.0,
171
+ -1.0,
172
+ );
173
+ expect(advanceStatechartInstance(createInstance(chart), 0.0) === 1).toEqual(true);
174
+ });
175
+ it('evaluates greater than or equal numeric comparison', () => {
176
+ const chart = createSingleTransitionChart(
177
+ [{ initialValue: 3.0, kind: 'Number', name: undefined }],
178
+ [condition(0, 'GreaterThanOrEqual', 3.0)],
179
+ 0.0,
180
+ -1.0,
181
+ );
182
+ expect(advanceStatechartInstance(createInstance(chart), 0.0) === 1).toEqual(true);
183
+ });
184
+ it('evaluates less than numeric comparison', () => {
185
+ const chart = createSingleTransitionChart(
186
+ [{ initialValue: 3.0, kind: 'Number', name: undefined }],
187
+ [condition(0, 'LessThan', 4.0)],
188
+ 0.0,
189
+ -1.0,
190
+ );
191
+ expect(advanceStatechartInstance(createInstance(chart), 0.0) === 1).toEqual(true);
192
+ });
193
+ it('evaluates less than or equal numeric comparison', () => {
194
+ const chart = createSingleTransitionChart(
195
+ [{ initialValue: 3.0, kind: 'Number', name: undefined }],
196
+ [condition(0, 'LessThanOrEqual', 3.0)],
197
+ 0.0,
198
+ -1.0,
199
+ );
200
+ expect(advanceStatechartInstance(createInstance(chart), 0.0) === 1).toEqual(true);
201
+ });
202
+ it('evaluates not equal numeric comparison', () => {
203
+ const chart = createSingleTransitionChart(
204
+ [{ initialValue: 3.0, kind: 'Number', name: undefined }],
205
+ [condition(0, 'NotEqual', 4.0)],
206
+ 0.0,
207
+ -1.0,
208
+ );
209
+ expect(advanceStatechartInstance(createInstance(chart), 0.0) === 1).toEqual(true);
84
210
  });
85
-
86
211
  it('reports blend progress without performing composition and changes state at completion', () => {
87
- const chart = createSingleTransitionChart([], [], { durationMs: 100 });
88
- const instance = createStatechartInstance(chart);
89
-
90
- expect(advanceStatechartInstance(instance, 40)).toBe(0);
91
- expect(instance.regionStates[0]).toBe(0);
92
- expect(getStatechartRegionBlend(instance, 0)).toBeCloseTo(0.4);
93
- expect(advanceStatechartInstance(instance, 60)).toBe(1);
94
- expect(instance.regionStates[0]).toBe(1);
95
- expect(getStatechartRegionBlend(instance, 0)).toBe(0);
212
+ const chart = createSingleTransitionChart([] as never[], [] as never[], 100.0, -1.0);
213
+ const instance = createInstance(chart);
214
+ expect(advanceStatechartInstance(instance, 40.0)).toEqual(0);
215
+ expect(instance!.regionStates[0]).toEqual(0);
216
+ expect(Math.abs(getStatechartRegionBlend(instance, 0) - 0.4) < 0.001).toBe(true);
217
+ expect(advanceStatechartInstance(instance, 60.0)).toEqual(1);
218
+ expect(instance!.regionStates[0]).toEqual(1);
219
+ expect(getStatechartRegionBlend(instance, 0)).toEqual(0.0);
96
220
  });
97
-
98
- it('accumulates elapsed time and evaluates exitTimeRatio against the caller-supplied duration', () => {
99
- const chart = createSingleTransitionChart([], [], { exitTimeRatio: 0.5 });
100
- const instance = createStatechartInstance(chart);
101
- setStatechartRegionDuration(instance, 0, 100);
102
-
103
- expect(advanceStatechartInstance(instance, 49)).toBe(0);
104
- expect(instance.regionElapsed[0]).toBe(49);
105
- expect(advanceStatechartInstance(instance, 1)).toBe(1);
106
- expect(instance.regionStates[0]).toBe(1);
107
- expect(instance.regionElapsed[0]).toBe(0);
108
- expect(instance.regionDuration[0]).toBe(0);
221
+ it('accumulates elapsed time and evaluates exit time ratio against caller supplied duration', () => {
222
+ const chart = createSingleTransitionChart([] as never[], [] as never[], 0.0, 0.5);
223
+ const instance = createInstance(chart);
224
+ setStatechartRegionDuration(instance, 0, 100.0);
225
+ expect(advanceStatechartInstance(instance, 49.0)).toEqual(0);
226
+ expect(instance!.regionElapsed[0]).toEqual(49.0);
227
+ expect(advanceStatechartInstance(instance, 1.0)).toEqual(1);
228
+ expect(instance!.regionStates[0]).toEqual(1);
229
+ expect(instance!.regionElapsed[0]).toEqual(0.0);
230
+ expect(instance!.regionDuration[0]).toEqual(0.0);
109
231
  });
110
-
111
232
  it('changes a region at most once per call even when the target has an immediate transition', () => {
112
- const chart: Statechart = {
233
+ const chart: StatechartRaw = {
113
234
  inputs: [],
235
+ name: undefined,
114
236
  regions: [
115
237
  {
116
238
  initialStateIndex: 0,
239
+ name: undefined,
117
240
  states: [
118
- { kind: StatechartAtomicStateKind, transitions: [transition(1)] },
119
- { kind: StatechartAtomicStateKind, transitions: [transition(2)] },
120
- { kind: StatechartAtomicStateKind, transitions: [] },
241
+ {
242
+ kind: String(StatechartAtomicStateKind),
243
+ name: undefined,
244
+ transitions: [transition(1, [] as never[], 0.0, -1.0)],
245
+ },
246
+ {
247
+ kind: String(StatechartAtomicStateKind),
248
+ name: undefined,
249
+ transitions: [transition(2, [] as never[], 0.0, -1.0)],
250
+ },
251
+ { kind: String(StatechartAtomicStateKind), name: undefined, transitions: [] },
121
252
  ],
122
253
  },
123
254
  ],
124
255
  };
125
- const instance = createStatechartInstance(chart);
126
-
127
- expect(advanceStatechartInstance(instance, 0)).toBe(1);
128
- expect(instance.regionStates[0]).toBe(1);
129
- expect(advanceStatechartInstance(instance, 0)).toBe(1);
130
- expect(instance.regionStates[0]).toBe(2);
256
+ const instance = createInstance(chart);
257
+ expect(advanceStatechartInstance(instance, 0.0)).toEqual(1);
258
+ expect(instance!.regionStates[0]).toEqual(1);
259
+ expect(advanceStatechartInstance(instance, 0.0)).toEqual(1);
260
+ expect(instance!.regionStates[0]).toEqual(2);
131
261
  });
132
-
133
- it('treats non-positive and non-finite time as no blend progress', () => {
134
- const chart = createSingleTransitionChart([], [], { durationMs: 100 });
135
- const instance = createStatechartInstance(chart);
136
-
137
- expect(advanceStatechartInstance(instance, -1)).toBe(0);
138
- expect(advanceStatechartInstance(instance, Number.NaN)).toBe(0);
139
- expect(instance.regionBlend[0]).toBe(0);
262
+ it('treats non positive and non finite time as no blend progress', () => {
263
+ const chart = createSingleTransitionChart([] as never[], [] as never[], 100.0, -1.0);
264
+ const instance = createInstance(chart);
265
+ expect(advanceStatechartInstance(instance, -1.0)).toEqual(0);
266
+ expect(advanceStatechartInstance(instance, Number.NaN)).toEqual(0);
267
+ expect(instance!.regionBlend[0]).toEqual(0.0);
140
268
  });
141
269
  });
142
270
 
143
271
  describe('createStatechartInstance', () => {
144
- it('creates independent typed-array actor state while retaining the immutable chart', () => {
145
- const chart: Statechart = {
272
+ it('creates independent typed array actor state while retaining the immutable chart', () => {
273
+ const chart: StatechartRaw = {
146
274
  inputs: [
147
- { initialValue: -2, kind: StatechartInputKind.Boolean },
148
- { initialValue: 3.5, kind: StatechartInputKind.Number },
149
- { initialValue: 0, kind: StatechartInputKind.Trigger },
275
+ { initialValue: -2.0, kind: 'Boolean', name: undefined },
276
+ { initialValue: 3.5, kind: 'Number', name: undefined },
277
+ { initialValue: 0.0, kind: 'Trigger', name: undefined },
150
278
  ],
151
279
  name: 'shared',
152
280
  regions: [
153
281
  {
154
282
  initialStateIndex: 1,
283
+ name: undefined,
155
284
  states: [
156
- { kind: StatechartNestedStateKind, transitions: [] },
157
- { kind: 'acme.CustomState', transitions: [] },
285
+ { kind: String(StatechartNestedStateKind), name: undefined, transitions: [] },
286
+ { kind: 'acme.CustomState', name: undefined, transitions: [] },
158
287
  ],
159
288
  },
160
289
  ],
161
- };
162
-
163
- const first = createStatechartInstance(chart);
164
- const second = createStatechartInstance(chart);
165
- expect(first.chart).toBe(chart);
166
- expect(first.chart).toBe(second.chart);
167
- expect(first.inputValues).toBeInstanceOf(Float64Array);
168
- expect([...first.inputValues]).toEqual([1, 3.5, 0]);
169
- expect(first.regionBlend).toBeInstanceOf(Float32Array);
170
- expect(first.regionDuration).toBeInstanceOf(Float64Array);
171
- expect(first.regionElapsed).toBeInstanceOf(Float64Array);
172
- expect(first.regionStates).toBeInstanceOf(Int32Array);
173
- expect(first.regionTransitions).toBeInstanceOf(Int32Array);
174
- expect([...first.regionStates]).toEqual([1]);
175
- expect([...first.regionTransitions]).toEqual([-1]);
176
- expect(first.durationGuard).toBeNull();
177
- expect(first.signals).toBeNull();
178
-
179
- first.inputValues[1] = 9;
180
- expect(second.inputValues[1]).toBe(3.5);
290
+ } as const;
291
+ const chartRef = chart;
292
+ const first = createStatechartInstance(chartRef);
293
+ const second = createStatechartInstance(chartRef);
294
+ expect(first!.chart === chartRef).toBe(true);
295
+ expect(second!.chart === chartRef).toBe(true);
296
+ expect(first!.inputValues.length).toEqual(3);
297
+ expect(first!.inputValues[0]).toEqual(1.0);
298
+ expect(first!.inputValues[1]).toEqual(3.5);
299
+ expect(first!.inputValues[2]).toEqual(0.0);
300
+ expect(first!.regionBlend.length).toEqual(1);
301
+ expect(first!.regionDuration.length).toEqual(1);
302
+ expect(first!.regionElapsed.length).toEqual(1);
303
+ expect(first!.regionStates.length).toEqual(1);
304
+ expect(first!.regionTransitions.length).toEqual(1);
305
+ expect(first!.regionStates[0]).toEqual(1);
306
+ expect(first!.regionTransitions[0]).toEqual(-1);
307
+ first!.inputValues[1] = 9.0;
308
+ expect(second!.inputValues[1]).toEqual(3.5);
181
309
  });
182
-
183
310
  it('rejects malformed authored indices as programmer errors', () => {
184
- const chart: Statechart = {
185
- inputs: [],
186
- regions: [{ initialStateIndex: 1, states: [{ kind: StatechartAtomicStateKind, transitions: [] }] }],
187
- };
188
- expect(() => createStatechartInstance(chart)).toThrow(RangeError);
311
+ expect(() => {
312
+ const chart: StatechartRaw = {
313
+ inputs: [],
314
+ name: undefined,
315
+ regions: [
316
+ {
317
+ initialStateIndex: 1,
318
+ name: undefined,
319
+ states: [{ kind: String(StatechartAtomicStateKind), name: undefined, transitions: [] }],
320
+ },
321
+ ],
322
+ };
323
+ createInstance(chart);
324
+ }).toThrow();
189
325
  });
190
-
191
- it('accepts nested and vendor-prefixed state kinds without closed dispatch', () => {
192
- const chart: Statechart = {
326
+ it('accepts nested and vendor prefixed state kinds without closed dispatch', () => {
327
+ const chart: StatechartRaw = {
193
328
  inputs: [],
329
+ name: undefined,
194
330
  regions: [
195
331
  {
196
332
  initialStateIndex: 0,
333
+ name: undefined,
197
334
  states: [
198
- { kind: StatechartNestedStateKind, transitions: [] },
199
- { kind: 'vendor.Special', transitions: [] },
335
+ { kind: String(StatechartNestedStateKind), name: undefined, transitions: [] },
336
+ { kind: 'vendor.Special', name: undefined, transitions: [] },
200
337
  ],
201
338
  },
202
339
  ],
203
340
  };
204
- expect(() => createStatechartInstance(chart)).not.toThrow();
341
+ createInstance(chart);
205
342
  });
206
343
  });
207
344
 
208
345
  describe('explainStatechartTransition', () => {
209
- it('returns an invalid-region diagnostic for the silent getter sentinel', () => {
210
- const explanation = explainStatechartTransition(createStatechartInstance(createEmptyChart()), 4);
346
+ it('returns an invalid region diagnostic for the silent getter sentinel', () => {
347
+ const explanation = explainStatechartTransition(createInstance(createEmptyChart()), 4);
211
348
  expect(explanation).toEqual({
212
- blend: -1,
349
+ blend: -1.0,
213
350
  conditionIndex: -1,
214
351
  regionIndex: 4,
215
352
  sourceStateIndex: -1,
216
- status: StatechartTransitionStatus.InvalidRegion,
353
+ status: 'InvalidRegion',
217
354
  targetStateIndex: -1,
218
355
  transitionIndex: -1,
219
356
  });
220
357
  });
221
-
222
358
  it('reports a state with no transitions', () => {
223
- const explanation = explainStatechartTransition(createStatechartInstance(createEmptyChart()), 0);
224
- expect(explanation.status).toBe(StatechartTransitionStatus.NoTransitions);
225
- expect(explanation.transitionIndex).toBe(-1);
359
+ const explanation = explainStatechartTransition(createInstance(createEmptyChart()), 0);
360
+ expect(explanation.status).toEqual('NoTransitions');
361
+ expect(explanation.transitionIndex).toEqual(-1);
226
362
  });
227
-
228
363
  it('identifies the first unmet condition', () => {
229
364
  const chart = createSingleTransitionChart(
230
- [{ initialValue: 0, kind: StatechartInputKind.Number }],
231
- [condition(0, StatechartComparison.GreaterThan, 2)],
365
+ [{ initialValue: 0.0, kind: 'Number', name: undefined }],
366
+ [condition(0, 'GreaterThan', 2.0)],
367
+ 0.0,
368
+ -1.0,
232
369
  );
233
- const explanation = explainStatechartTransition(createStatechartInstance(chart), 0);
234
- expect(explanation.status).toBe(StatechartTransitionStatus.ConditionsUnmet);
235
- expect(explanation.conditionIndex).toBe(0);
236
- expect(explanation.targetStateIndex).toBe(1);
370
+ const explanation = explainStatechartTransition(createInstance(chart), 0);
371
+ expect(explanation.status).toEqual('ConditionsUnmet');
372
+ expect(explanation.conditionIndex).toEqual(0);
373
+ expect(explanation.targetStateIndex).toEqual(1);
237
374
  });
238
-
239
375
  it('reports ready and transitioning states without mutation', () => {
240
- const chart = createSingleTransitionChart([], [], { durationMs: 100 });
241
- const instance = createStatechartInstance(chart);
242
- expect(explainStatechartTransition(instance, 0).status).toBe(StatechartTransitionStatus.Ready);
243
- advanceStatechartInstance(instance, 25);
376
+ const chart = createSingleTransitionChart([] as never[], [] as never[], 100.0, -1.0);
377
+ const instance = createInstance(chart);
378
+ expect(explainStatechartTransition(instance, 0).status).toEqual('Ready');
379
+ advanceStatechartInstance(instance, 25.0);
244
380
  const explanation = explainStatechartTransition(instance, 0);
245
- expect(explanation.status).toBe(StatechartTransitionStatus.Transitioning);
246
- expect(explanation.blend).toBeCloseTo(0.25);
247
- expect(explanation.transitionIndex).toBe(0);
381
+ expect(explanation.status).toEqual('Transitioning');
382
+ expect(Math.abs(explanation.blend - 0.25) < 0.001).toBe(true);
383
+ expect(explanation.transitionIndex).toEqual(0);
248
384
  });
249
-
250
385
  it('reports a satisfied guard waiting on exit time', () => {
251
- const chart = createSingleTransitionChart([], [], { exitTimeRatio: 0.5 });
252
- const instance = createStatechartInstance(chart);
253
- setStatechartRegionDuration(instance, 0, 100);
386
+ const chart = createSingleTransitionChart([] as never[], [] as never[], 0.0, 0.5);
387
+ const instance = createInstance(chart);
388
+ setStatechartRegionDuration(instance, 0, 100.0);
254
389
  const explanation = explainStatechartTransition(instance, 0);
255
- expect(explanation.status).toBe(StatechartTransitionStatus.ExitTimePending);
256
- expect(explanation.conditionIndex).toBe(-1);
390
+ expect(explanation.status).toEqual('ExitTimePending');
391
+ expect(explanation.conditionIndex).toEqual(-1);
257
392
  });
258
-
259
- it('reports a missing duration that runtime coerces to no exit-time requirement', () => {
260
- const chart = createSingleTransitionChart([], [], { exitTimeRatio: 0.5 });
261
- const explanation = explainStatechartTransition(createStatechartInstance(chart), 0);
262
- expect(explanation.status).toBe(StatechartTransitionStatus.MissingRegionDuration);
263
- expect(explanation.transitionIndex).toBe(0);
393
+ it('reports a missing duration that runtime coerces to no exit time requirement', () => {
394
+ const chart = createSingleTransitionChart([] as never[], [] as never[], 0.0, 0.5);
395
+ const explanation = explainStatechartTransition(createInstance(chart), 0);
396
+ expect(explanation.status).toEqual('MissingRegionDuration');
397
+ expect(explanation.transitionIndex).toEqual(0);
264
398
  });
265
399
  });
266
400
 
267
401
  describe('fireStatechartTrigger', () => {
268
402
  it('latches a trigger until all regions see the next advance and ignores condition value', () => {
269
- const instance = createStatechartInstance(createTwoRegionTriggerChart());
403
+ const instance = createInstance(createTwoRegionTriggerChart());
270
404
  fireStatechartTrigger(instance, 0);
271
- expect(instance.inputValues[0]).toBe(1);
272
- expect(advanceStatechartInstance(instance, 0)).toBe(2);
273
- expect(instance.inputValues[0]).toBe(0);
405
+ expect(instance!.inputValues[0]).toEqual(1.0);
406
+ expect(advanceStatechartInstance(instance, 0.0)).toEqual(2);
407
+ expect(instance!.inputValues[0]).toEqual(0.0);
274
408
  });
275
-
276
- it('throws for an invalid index or non-trigger input', () => {
277
- const instance = createStatechartInstance(
278
- createSingleTransitionChart([{ initialValue: 0, kind: StatechartInputKind.Number }]),
279
- );
280
- expect(() => fireStatechartTrigger(instance, -1)).toThrow(RangeError);
281
- expect(() => fireStatechartTrigger(instance, 0)).toThrow(TypeError);
409
+ it('throws for an invalid index', () => {
410
+ expect(() => {
411
+ const chart = createSingleTransitionChart(
412
+ [{ initialValue: 0.0, kind: 'Number', name: undefined }],
413
+ [] as never[],
414
+ 0.0,
415
+ -1.0,
416
+ );
417
+ const instance = createInstance(chart);
418
+ fireStatechartTrigger(instance, -1);
419
+ }).toThrow();
420
+ });
421
+ it('throws for non trigger input', () => {
422
+ expect(() => {
423
+ const chart = createSingleTransitionChart(
424
+ [{ initialValue: 0.0, kind: 'Number', name: undefined }],
425
+ [] as never[],
426
+ 0.0,
427
+ -1.0,
428
+ );
429
+ const instance = createInstance(chart);
430
+ fireStatechartTrigger(instance, 0);
431
+ }).toThrow();
282
432
  });
283
433
  });
284
434
 
285
435
  describe('getStatechartInputIndex', () => {
286
- it('returns the first matching input index and -1 when absent', () => {
287
- const chart: Statechart = {
436
+ it('returns the first matching input index and negative one when absent', () => {
437
+ const chart: StatechartRaw = {
288
438
  inputs: [
289
- { initialValue: 0, kind: StatechartInputKind.Number, name: 'speed' },
290
- { initialValue: 1, kind: StatechartInputKind.Number, name: 'speed' },
439
+ { initialValue: 0.0, kind: 'Number', name: 'speed' },
440
+ { initialValue: 1.0, kind: 'Number', name: 'speed' },
291
441
  ],
442
+ name: undefined,
292
443
  regions: [],
293
- };
294
- expect(getStatechartInputIndex(chart, 'speed')).toBe(0);
295
- expect(getStatechartInputIndex(chart, 'missing')).toBe(-1);
444
+ } as const;
445
+ expect(getStatechartInputIndex(chart, 'speed')).toEqual(0);
446
+ expect(getStatechartInputIndex(chart, 'missing')).toEqual(-1);
296
447
  });
297
448
  });
298
449
 
299
450
  describe('getStatechartRegionBlend', () => {
300
- it('returns a region blend and -1 for invalid regions', () => {
301
- const instance = createStatechartInstance(createEmptyChart());
302
- instance.regionBlend[0] = 0.4;
303
- expect(getStatechartRegionBlend(instance, 0)).toBeCloseTo(0.4);
304
- expect(getStatechartRegionBlend(instance, -1)).toBe(-1);
305
- expect(getStatechartRegionBlend(instance, 1)).toBe(-1);
451
+ it('returns a region blend and negative one for invalid regions', () => {
452
+ const instance = createInstance(createEmptyChart());
453
+ instance!.regionBlend[0] = 0.4;
454
+ expect(Math.abs(getStatechartRegionBlend(instance, 0) - 0.4) < 0.001).toBe(true);
455
+ expect(getStatechartRegionBlend(instance, -1)).toEqual(-1.0);
456
+ expect(getStatechartRegionBlend(instance, 1)).toEqual(-1.0);
306
457
  });
307
458
  });
308
459
 
309
460
  describe('getStatechartRegionState', () => {
310
- it('returns a region state and -1 for invalid regions', () => {
311
- const instance = createStatechartInstance(createEmptyChart());
312
- expect(getStatechartRegionState(instance, 0)).toBe(0);
313
- expect(getStatechartRegionState(instance, -1)).toBe(-1);
314
- expect(getStatechartRegionState(instance, 1)).toBe(-1);
461
+ it('returns a region state and negative one for invalid regions', () => {
462
+ const instance = createInstance(createEmptyChart());
463
+ expect(getStatechartRegionState(instance, 0)).toEqual(0);
464
+ expect(getStatechartRegionState(instance, -1)).toEqual(-1);
465
+ expect(getStatechartRegionState(instance, 1)).toEqual(-1);
315
466
  });
316
467
  });
317
468
 
318
- describe('initializeStatechartInstance', () => {
319
- it('is the construction initializer of createStatechartInstance', () => {
320
- expect(typeof initializeStatechartInstance).toBe('function');
469
+ describe('initializeStatechartInstancePortable', () => {
470
+ it('backs the public constructor with initialized region state', () => {
471
+ const instance = createStatechartInstance(createEmptyChart());
472
+ expect(instance!.regionStates[0]).toEqual(0);
473
+ expect(instance!.regionTransitions[0]).toEqual(-1);
321
474
  });
322
475
  });
323
476
 
324
477
  describe('setStatechartBooleanInput', () => {
325
- it('writes the Boolean input vocabulary as numeric 0/1', () => {
326
- const instance = createStatechartInstance(
327
- createSingleTransitionChart([{ initialValue: 0, kind: StatechartInputKind.Boolean }]),
478
+ it('writes the boolean input vocabulary as numeric 0 1', () => {
479
+ const chart = createSingleTransitionChart(
480
+ [{ initialValue: 0.0, kind: 'Boolean', name: undefined }],
481
+ [] as never[],
482
+ 0.0,
483
+ -1.0,
328
484
  );
485
+ const instance = createInstance(chart);
329
486
  setStatechartBooleanInput(instance, 0, true);
330
- expect(instance.inputValues[0]).toBe(1);
487
+ expect(instance!.inputValues[0]).toEqual(1.0);
331
488
  setStatechartBooleanInput(instance, 0, false);
332
- expect(instance.inputValues[0]).toBe(0);
489
+ expect(instance!.inputValues[0]).toEqual(0.0);
333
490
  });
334
-
335
- it('throws for an invalid index or non-Boolean input', () => {
336
- const instance = createStatechartInstance(
337
- createSingleTransitionChart([{ initialValue: 0, kind: StatechartInputKind.Number }]),
338
- );
339
- expect(() => setStatechartBooleanInput(instance, 1, true)).toThrow(RangeError);
340
- expect(() => setStatechartBooleanInput(instance, 0, true)).toThrow(TypeError);
491
+ it('throws for an invalid index', () => {
492
+ expect(() => {
493
+ const chart = createSingleTransitionChart(
494
+ [{ initialValue: 0.0, kind: 'Number', name: undefined }],
495
+ [] as never[],
496
+ 0.0,
497
+ -1.0,
498
+ );
499
+ const instance = createInstance(chart);
500
+ setStatechartBooleanInput(instance, 1, true);
501
+ }).toThrow();
502
+ });
503
+ it('throws for non boolean input', () => {
504
+ expect(() => {
505
+ const chart = createSingleTransitionChart(
506
+ [{ initialValue: 0.0, kind: 'Number', name: undefined }],
507
+ [] as never[],
508
+ 0.0,
509
+ -1.0,
510
+ );
511
+ const instance = createInstance(chart);
512
+ setStatechartBooleanInput(instance, 0, true);
513
+ }).toThrow();
341
514
  });
342
515
  });
343
516
 
344
517
  describe('setStatechartNumberInput', () => {
345
518
  it('writes an exact numeric value', () => {
346
- const instance = createStatechartInstance(
347
- createSingleTransitionChart([{ initialValue: 0, kind: StatechartInputKind.Number }]),
519
+ const chart = createSingleTransitionChart(
520
+ [{ initialValue: 0.0, kind: 'Number', name: undefined }],
521
+ [] as never[],
522
+ 0.0,
523
+ -1.0,
348
524
  );
525
+ const instance = createInstance(chart);
349
526
  setStatechartNumberInput(instance, 0, -3.25);
350
- expect(instance.inputValues[0]).toBe(-3.25);
527
+ expect(instance!.inputValues[0]).toEqual(-3.25);
351
528
  });
352
-
353
- it('throws for an invalid index or non-Number input', () => {
354
- const instance = createStatechartInstance(
355
- createSingleTransitionChart([{ initialValue: 0, kind: StatechartInputKind.Boolean }]),
356
- );
357
- expect(() => setStatechartNumberInput(instance, 1, 2)).toThrow(RangeError);
358
- expect(() => setStatechartNumberInput(instance, 0, 2)).toThrow(TypeError);
529
+ it('throws for an invalid index', () => {
530
+ expect(() => {
531
+ const chart = createSingleTransitionChart(
532
+ [{ initialValue: 0.0, kind: 'Boolean', name: undefined }],
533
+ [] as never[],
534
+ 0.0,
535
+ -1.0,
536
+ );
537
+ const instance = createInstance(chart);
538
+ setStatechartNumberInput(instance, 1, 2.0);
539
+ }).toThrow();
359
540
  });
360
- });
361
-
362
- function condition(inputIndex: number, comparison: StatechartComparison, value: number): StatechartCondition {
363
- return { comparison, inputIndex, value };
364
- }
365
-
366
- function createEmptyChart(): Statechart {
367
- return {
368
- inputs: [],
369
- regions: [{ initialStateIndex: 0, states: [{ kind: StatechartAtomicStateKind, transitions: [] }] }],
370
- };
371
- }
372
-
373
- function createSingleTransitionChart(
374
- inputs: Statechart['inputs'],
375
- conditions: readonly StatechartCondition[] = [],
376
- options: Partial<Pick<StatechartTransition, 'durationMs' | 'exitTimeRatio'>> = {},
377
- ): Statechart {
378
- return {
379
- inputs,
380
- regions: [
381
- {
382
- initialStateIndex: 0,
383
- states: [
384
- {
385
- kind: StatechartAtomicStateKind,
386
- transitions: [transition(1, conditions, options)],
387
- },
388
- { kind: StatechartAtomicStateKind, transitions: [] },
389
- ],
390
- },
391
- ],
392
- };
393
- }
394
-
395
- function createTwoRegionTriggerChart(): Statechart {
396
- const triggerTransition = transition(1, [condition(0, StatechartComparison.GreaterThan, 999)]);
397
- const region = () => ({
398
- initialStateIndex: 0,
399
- states: [
400
- { kind: StatechartAtomicStateKind, transitions: [triggerTransition] },
401
- { kind: StatechartAtomicStateKind, transitions: [] },
402
- ],
541
+ it('throws for non number input', () => {
542
+ expect(() => {
543
+ const chart = createSingleTransitionChart(
544
+ [{ initialValue: 0.0, kind: 'Boolean', name: undefined }],
545
+ [] as never[],
546
+ 0.0,
547
+ -1.0,
548
+ );
549
+ const instance = createInstance(chart);
550
+ setStatechartNumberInput(instance, 0, 2.0);
551
+ }).toThrow();
403
552
  });
404
- return {
405
- inputs: [{ initialValue: 0, kind: StatechartInputKind.Trigger, name: 'go' }],
406
- regions: [region(), region()],
407
- };
408
- }
553
+ });
409
554
 
410
- function transition(
411
- targetStateIndex: number,
412
- conditions: readonly StatechartCondition[] = [],
413
- options: Partial<Pick<StatechartTransition, 'durationMs' | 'exitTimeRatio'>> = {},
414
- ): StatechartTransition {
415
- return {
416
- conditions,
417
- durationMs: options.durationMs ?? 0,
418
- exitTimeRatio: options.exitTimeRatio ?? -1,
419
- targetStateIndex,
420
- };
421
- }
422
555
  describe('setStatechartRegionDuration', () => {
423
- it('sets the plain per-region exit-time denominator', () => {
424
- const instance = createStatechartInstance(createEmptyChart());
425
- setStatechartRegionDuration(instance, 0, 250);
426
- expect(instance.regionDuration[0]).toBe(250);
556
+ it('sets the plain per region exit time denominator', () => {
557
+ const instance = createInstance(createEmptyChart());
558
+ setStatechartRegionDuration(instance, 0, 250.0);
559
+ expect(instance!.regionDuration[0]).toEqual(250.0);
427
560
  });
428
-
429
561
  it('accepts zero as an explicit unavailable duration', () => {
430
- const instance = createStatechartInstance(createEmptyChart());
431
- setStatechartRegionDuration(instance, 0, 0);
432
- expect(instance.regionDuration[0]).toBe(0);
562
+ const instance = createInstance(createEmptyChart());
563
+ setStatechartRegionDuration(instance, 0, 0.0);
564
+ expect(instance!.regionDuration[0]).toEqual(0.0);
433
565
  });
434
-
435
- it('throws for an invalid region or invalid duration', () => {
436
- const instance = createStatechartInstance(createEmptyChart());
437
- expect(() => setStatechartRegionDuration(instance, 1, 1)).toThrow(RangeError);
438
- expect(() => setStatechartRegionDuration(instance, 0, -1)).toThrow(RangeError);
439
- expect(() => setStatechartRegionDuration(instance, 0, Number.NaN)).toThrow(RangeError);
566
+ it('throws for an invalid region', () => {
567
+ expect(() => {
568
+ const instance = createInstance(createEmptyChart());
569
+ setStatechartRegionDuration(instance, 1, 1.0);
570
+ }).toThrow();
571
+ });
572
+ it('throws for negative duration', () => {
573
+ expect(() => {
574
+ const instance = createInstance(createEmptyChart());
575
+ setStatechartRegionDuration(instance, 0, -1.0);
576
+ }).toThrow();
577
+ });
578
+ it('throws for nan duration', () => {
579
+ expect(() => {
580
+ const instance = createInstance(createEmptyChart());
581
+ setStatechartRegionDuration(instance, 0, Number.NaN);
582
+ }).toThrow();
440
583
  });
441
584
  });