@flighthq/flow 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 (44) 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 +6 -2
  5. package/dist/contract.d.ts.map +1 -1
  6. package/dist/contract.flow-types.d.ts +3 -0
  7. package/dist/contract.flow-types.d.ts.map +1 -0
  8. package/dist/contract.flow-types.js +2 -0
  9. package/dist/contract.flow-types.js.map +1 -0
  10. package/dist/contract.js +5 -2
  11. package/dist/contract.js.map +1 -1
  12. package/dist/flow.d.ts +46 -11
  13. package/dist/flow.d.ts.map +1 -1
  14. package/dist/flow.js +172 -93
  15. package/dist/flow.js.map +1 -1
  16. package/dist/flowGuards.d.ts +22 -4
  17. package/dist/flowGuards.d.ts.map +1 -1
  18. package/dist/flowGuards.js +72 -10
  19. package/dist/flowGuards.js.map +1 -1
  20. package/dist/flowStackCompat.d.ts +20 -0
  21. package/dist/flowStackCompat.d.ts.map +1 -0
  22. package/dist/flowStackCompat.js +47 -0
  23. package/dist/flowStackCompat.js.map +1 -0
  24. package/dist/flowTransitions.d.ts +3 -0
  25. package/dist/flowTransitions.d.ts.map +1 -0
  26. package/dist/flowTransitions.js +14 -0
  27. package/dist/flowTransitions.js.map +1 -0
  28. package/dist/flowTypes.d.ts +33 -0
  29. package/dist/flowTypes.d.ts.map +1 -0
  30. package/dist/flowTypes.js +4 -0
  31. package/dist/flowTypes.js.map +1 -0
  32. package/dist/index.d.ts +3 -2
  33. package/dist/index.d.ts.map +1 -1
  34. package/dist/index.js +4 -2
  35. package/dist/index.js.map +1 -1
  36. package/dist/types.d.ts +24 -0
  37. package/dist/types.d.ts.map +1 -0
  38. package/dist/types.js +4 -0
  39. package/dist/types.js.map +1 -0
  40. package/package.json +6 -5
  41. package/src/flow.test.ts +440 -175
  42. package/src/flowGuards.test.ts +131 -12
  43. package/src/flowStackCompat.test.ts +99 -0
  44. package/src/flowTransitions.test.ts +26 -0
package/src/flow.test.ts CHANGED
@@ -1,8 +1,14 @@
1
- import type { FlowState } from '@flighthq/types/contract';
1
+ // Generated from crates/flight-flow/tests/flow_test.rs by flight-compiler.
2
+ // Rust is authoritative; run `npm run generate` after changing it.
3
+
4
+ import * as flightEntity from '@flighthq/entity/contract';
5
+ import { createLogState } from '@flighthq/log/contract';
6
+ import { describe, expect, it } from 'vitest';
2
7
 
3
8
  import {
4
9
  clearFlowStack,
5
10
  createFlowStack,
11
+ disableFlowGuards,
6
12
  getActiveFlowState,
7
13
  getFlowStackDepth,
8
14
  getFlowStackVisibleStates,
@@ -11,284 +17,543 @@ import {
11
17
  pushFlowState,
12
18
  replaceFlowState,
13
19
  updateFlowStack,
14
- } from './flow';
20
+ } from './contract.ts';
21
+ import type { FlowGuardContext, FlowGuardState, FlowGuardStateRef, FlowState } from './contract.ts';
22
+
23
+ function guardState(): FlowGuardStateRef {
24
+ const state = { enabled: false, transitionDepth: 0, context: { logState: createLogState(), clock: () => 0.0 } };
25
+ disableFlowGuards(state);
26
+ return state;
27
+ }
28
+
29
+ function state(state: FlowState): FlowState {
30
+ return state;
31
+ }
32
+
33
+ function labeledState(name: string, log: { value: string[] }): FlowState {
34
+ const enterName = String(name);
35
+ const exitName = String(name);
36
+ const pauseName = String(name);
37
+ const resumeName = String(name);
38
+ const updateName = String(name);
39
+ const enterLog = log;
40
+ const exitLog = log;
41
+ const pauseLog = log;
42
+ const resumeLog = log;
43
+ const updateLog = log;
44
+ return state({
45
+ name: String(name),
46
+ onEnter: () => {
47
+ return enterLog.value.push(`${enterName}.enter`);
48
+ },
49
+ onExit: () => {
50
+ return exitLog.value.push(`${exitName}.exit`);
51
+ },
52
+ onPause: () => {
53
+ return pauseLog.value.push(`${pauseName}.pause`);
54
+ },
55
+ onResume: () => {
56
+ return resumeLog.value.push(`${resumeName}.resume`);
57
+ },
58
+ onUpdate: (dt: number) => {
59
+ return updateLog.value.push(`${updateName}.update:${dt}`);
60
+ },
61
+ renderBelow: undefined,
62
+ updateBelow: undefined,
63
+ });
64
+ }
65
+
66
+ function plain(name: string): FlowState {
67
+ return state({
68
+ name: String(name),
69
+ onEnter: undefined,
70
+ onExit: undefined,
71
+ onPause: undefined,
72
+ onResume: undefined,
73
+ onUpdate: undefined,
74
+ renderBelow: undefined,
75
+ updateBelow: undefined,
76
+ });
77
+ }
78
+
79
+ function takeOnce(slot: { value: boolean[] }): boolean {
80
+ let values = slot.value;
81
+ if (values.length !== 0) {
82
+ return false;
83
+ }
84
+ values.push(true);
85
+ return true;
86
+ }
15
87
 
16
88
  describe('clearFlowStack', () => {
17
- it('exits every state top-to-bottom and empties the stack', () => {
18
- const log: string[] = [];
89
+ it('exits every state top to bottom and empties the stack', () => {
90
+ const log: { value: string[] } = { value: [] as never[] };
19
91
  const stack = createFlowStack();
20
- pushFlowState(stack, labeledState('A', log));
21
- pushFlowState(stack, labeledState('B', log));
22
- pushFlowState(stack, labeledState('C', log));
23
- log.length = 0;
92
+ const guards = guardState();
93
+ pushFlowState(stack, labeledState('A', log), guards);
94
+ pushFlowState(stack, labeledState('B', log), guards);
95
+ pushFlowState(stack, labeledState('C', log), guards);
96
+ log.value = [] as never[];
24
97
  clearFlowStack(stack);
25
- expect(log).toEqual(['C.exit', 'B.exit', 'A.exit']);
26
- expect(stack.states.length).toBe(0);
98
+ expect(log.value).toEqual(['C.exit', 'B.exit', 'A.exit']);
99
+ expect(getFlowStackDepth(stack)).toEqual(0);
27
100
  });
28
-
29
- it('is a no-op on an empty stack', () => {
101
+ it('is a no op on an empty stack', () => {
30
102
  const stack = createFlowStack();
31
- expect(() => clearFlowStack(stack)).not.toThrow();
32
- expect(stack.states.length).toBe(0);
103
+ clearFlowStack(stack);
104
+ expect(getFlowStackDepth(stack)).toEqual(0);
105
+ });
106
+ it('exits while the states are still on the stack', () => {
107
+ const stack = createFlowStack();
108
+ const guards = guardState();
109
+ const seen: { value: number[] } = { value: [] as never[] };
110
+ for (const name of ['A', 'B']) {
111
+ const observer = stack;
112
+ const depths = seen;
113
+ pushFlowState(
114
+ stack,
115
+ state({
116
+ name: String(name),
117
+ onEnter: undefined,
118
+ onExit: () => {
119
+ depths.value.push(getFlowStackDepth(observer));
120
+ },
121
+ onPause: undefined,
122
+ onResume: undefined,
123
+ onUpdate: undefined,
124
+ renderBelow: undefined,
125
+ updateBelow: undefined,
126
+ }),
127
+ guards,
128
+ );
129
+ }
130
+ clearFlowStack(stack);
131
+ expect(seen.value).toEqual([2, 2]);
132
+ expect(getFlowStackDepth(stack)).toEqual(0);
33
133
  });
34
134
  });
35
135
 
36
136
  describe('createFlowStack', () => {
37
137
  it('allocates an empty stack', () => {
38
138
  const stack = createFlowStack();
39
- expect(stack.states).toEqual([]);
139
+ expect(getFlowStackDepth(stack)).toEqual(0);
40
140
  });
41
-
42
141
  it('allocates a fresh independent stack each call', () => {
43
142
  const a = createFlowStack();
44
143
  const b = createFlowStack();
45
- expect(a).not.toBe(b);
46
- expect(a.states).not.toBe(b.states);
144
+ const guards = guardState();
145
+ pushFlowState(a, plain('A'), guards);
146
+ expect(getFlowStackDepth(b)).toEqual(0);
147
+ });
148
+ it('allocates an entity with an empty runtime slot', () => {
149
+ const stack = createFlowStack();
150
+ expect(!flightEntity.hasEntityRuntime(stack!)).toBe(true);
47
151
  });
48
152
  });
49
153
 
50
154
  describe('getActiveFlowState', () => {
51
155
  it('returns the top of the stack', () => {
52
156
  const stack = createFlowStack();
53
- const a = { name: 'A' };
54
- const b = { name: 'B' };
55
- pushFlowState(stack, a);
56
- pushFlowState(stack, b);
57
- expect(getActiveFlowState(stack)).toBe(b);
157
+ const guards = guardState();
158
+ const b = plain('B');
159
+ pushFlowState(stack, plain('A'), guards);
160
+ pushFlowState(stack, b, guards);
161
+ expect(getActiveFlowState(stack)! === b).toBe(true);
58
162
  });
59
-
60
- it('returns null on an empty stack', () => {
163
+ it('returns none on an empty stack', () => {
61
164
  const stack = createFlowStack();
62
- expect(getActiveFlowState(stack)).toBeNull();
165
+ const fallback = plain('fallback');
166
+ const active = getActiveFlowState(stack) ?? fallback;
167
+ expect(active === fallback).toBe(true);
63
168
  });
64
169
  });
65
170
 
66
171
  describe('getFlowStackDepth', () => {
67
172
  it('counts the states on the stack', () => {
68
173
  const stack = createFlowStack();
69
- expect(getFlowStackDepth(stack)).toBe(0);
70
- pushFlowState(stack, { name: 'A' });
71
- pushFlowState(stack, { name: 'B' });
72
- expect(getFlowStackDepth(stack)).toBe(2);
174
+ const guards = guardState();
175
+ expect(getFlowStackDepth(stack)).toEqual(0);
176
+ pushFlowState(stack, plain('A'), guards);
177
+ pushFlowState(stack, plain('B'), guards);
178
+ expect(getFlowStackDepth(stack)).toEqual(2);
73
179
  popFlowState(stack);
74
- expect(getFlowStackDepth(stack)).toBe(1);
180
+ expect(getFlowStackDepth(stack)).toEqual(1);
75
181
  });
76
182
  });
77
183
 
78
184
  describe('getFlowStackVisibleStates', () => {
79
185
  it('fills only the top when it is opaque', () => {
80
186
  const stack = createFlowStack();
81
- const a = { name: 'A' };
82
- const b = { name: 'B' };
83
- pushFlowState(stack, a);
84
- pushFlowState(stack, b);
85
- const out: FlowState[] = [];
86
- getFlowStackVisibleStates(stack, out);
87
- expect(out).toEqual([b]);
187
+ const guards = guardState();
188
+ pushFlowState(stack, plain('A'), guards);
189
+ const b = plain('B');
190
+ pushFlowState(stack, b, guards);
191
+ let out = [] as never[];
192
+ getFlowStackVisibleStates(out, stack);
193
+ expect(out.length).toEqual(1);
194
+ expect(out[0] === b).toBe(true);
88
195
  });
89
-
90
- it('includes the contiguous renderBelow run bottom-to-top', () => {
91
- const stack = createFlowStack();
92
- const a = { name: 'A' };
93
- const b: FlowState = { name: 'B', renderBelow: true };
94
- const c: FlowState = { name: 'C', renderBelow: true };
95
- pushFlowState(stack, a);
96
- pushFlowState(stack, b);
97
- pushFlowState(stack, c);
98
- const out: FlowState[] = [];
99
- getFlowStackVisibleStates(stack, out);
100
- expect(out).toEqual([a, b, c]);
196
+ it('includes the contiguous render below run bottom to top', () => {
197
+ const stack = createFlowStack();
198
+ const guards = guardState();
199
+ const a = plain('A');
200
+ let b: FlowState = {
201
+ name: 'B',
202
+ onEnter: undefined,
203
+ onExit: undefined,
204
+ onPause: undefined,
205
+ onResume: undefined,
206
+ onUpdate: undefined,
207
+ renderBelow: true,
208
+ updateBelow: undefined,
209
+ };
210
+ b.renderBelow = true;
211
+ b = state(b);
212
+ let c: FlowState = {
213
+ name: 'C',
214
+ onEnter: undefined,
215
+ onExit: undefined,
216
+ onPause: undefined,
217
+ onResume: undefined,
218
+ onUpdate: undefined,
219
+ renderBelow: true,
220
+ updateBelow: undefined,
221
+ };
222
+ c.renderBelow = true;
223
+ c = state(c);
224
+ pushFlowState(stack, a, guards);
225
+ pushFlowState(stack, b, guards);
226
+ pushFlowState(stack, c, guards);
227
+ let out = [] as never[];
228
+ getFlowStackVisibleStates(out, stack);
229
+ expect(out.length).toEqual(3);
230
+ expect(out[0] === a).toBe(true);
231
+ expect(out[1] === b).toBe(true);
232
+ expect(out[2] === c).toBe(true);
101
233
  });
102
-
103
234
  it('stops at the first opaque state below a translucent overlay', () => {
104
235
  const stack = createFlowStack();
105
- const a = { name: 'A' };
106
- const b = { name: 'B' };
107
- const c: FlowState = { name: 'C', renderBelow: true };
108
- pushFlowState(stack, a);
109
- pushFlowState(stack, b);
110
- pushFlowState(stack, c);
111
- const out: FlowState[] = [];
112
- getFlowStackVisibleStates(stack, out);
113
- expect(out).toEqual([b, c]);
236
+ const guards = guardState();
237
+ const b = plain('B');
238
+ const c = state({
239
+ name: 'C',
240
+ onEnter: undefined,
241
+ onExit: undefined,
242
+ onPause: undefined,
243
+ onResume: undefined,
244
+ onUpdate: undefined,
245
+ renderBelow: true,
246
+ updateBelow: undefined,
247
+ });
248
+ pushFlowState(stack, plain('A'), guards);
249
+ pushFlowState(stack, b, guards);
250
+ pushFlowState(stack, c, guards);
251
+ let out = [] as never[];
252
+ getFlowStackVisibleStates(out, stack);
253
+ expect(out.length).toEqual(2);
254
+ expect(out[0] === b).toBe(true);
255
+ expect(out[1] === c).toBe(true);
114
256
  });
115
-
116
- it('clears the out array before filling and can be reused', () => {
257
+ it('clears the out list before filling and can be reused', () => {
117
258
  const stack = createFlowStack();
118
- const a = { name: 'A' };
119
- pushFlowState(stack, a);
120
- const out: FlowState[] = [{ name: 'stale' }, { name: 'leftover' }];
121
- getFlowStackVisibleStates(stack, out);
122
- expect(out).toEqual([a]);
259
+ const guards = guardState();
260
+ const a = plain('A');
261
+ pushFlowState(stack, a, guards);
262
+ const stale = plain('stale');
263
+ let out = [stale, stale];
264
+ getFlowStackVisibleStates(out, stack);
265
+ expect(out.length).toEqual(1);
266
+ expect(out[0] === a).toBe(true);
123
267
  });
124
-
125
- it('leaves the out array empty for an empty stack', () => {
268
+ it('leaves the out list empty for an empty stack', () => {
126
269
  const stack = createFlowStack();
127
- const out: FlowState[] = [{ name: 'stale' }];
128
- getFlowStackVisibleStates(stack, out);
129
- expect(out).toEqual([]);
270
+ const stale = plain('stale');
271
+ let out = [stale];
272
+ getFlowStackVisibleStates(out, stack);
273
+ expect(out.length === 0).toBe(true);
130
274
  });
131
275
  });
132
276
 
133
277
  describe('initializeFlowStack', () => {
134
- it('is the construction initializer of createFlowStack', () => {
135
- expect(typeof initializeFlowStack).toBe('function');
278
+ it('is the construction initializer of create flow stack', () => {
279
+ const stack = createFlowStack();
280
+ stack!.states.push(plain('stale'));
281
+ initializeFlowStack(stack!);
282
+ expect(stack!.states.length === 0).toBe(true);
136
283
  });
137
284
  });
138
285
 
139
286
  describe('popFlowState', () => {
140
- it('exits the top and resumes the revealed state, returning the popped state', () => {
141
- const log: string[] = [];
287
+ it('exits the top and resumes the revealed state returning the popped state', () => {
288
+ const log: { value: string[] } = { value: [] as never[] };
142
289
  const stack = createFlowStack();
143
- const a = labeledState('A', log);
290
+ const guards = guardState();
291
+ pushFlowState(stack, labeledState('A', log), guards);
144
292
  const b = labeledState('B', log);
145
- pushFlowState(stack, a);
146
- pushFlowState(stack, b);
147
- log.length = 0;
148
- const popped = popFlowState(stack);
149
- expect(log).toEqual(['B.exit', 'A.resume']);
150
- expect(popped).toBe(b);
151
- expect(stack.states.length).toBe(1);
293
+ pushFlowState(stack, b, guards);
294
+ log.value = [] as never[];
295
+ const popped = popFlowState(stack)!;
296
+ expect(log.value).toEqual(['B.exit', 'A.resume']);
297
+ expect(popped === b).toBe(true);
298
+ expect(getFlowStackDepth(stack)).toEqual(1);
152
299
  });
153
-
154
- it('returns null when the stack is empty', () => {
300
+ it('returns none when the stack is empty', () => {
155
301
  const stack = createFlowStack();
156
- expect(popFlowState(stack)).toBeNull();
302
+ const fallback = plain('fallback');
303
+ const popped = popFlowState(stack) ?? fallback;
304
+ expect(popped === fallback).toBe(true);
157
305
  });
158
-
159
306
  it('exits the last state without resuming anything below', () => {
160
- const log: string[] = [];
307
+ const log: { value: string[] } = { value: [] as never[] };
161
308
  const stack = createFlowStack();
162
- pushFlowState(stack, labeledState('A', log));
163
- log.length = 0;
309
+ const guards = guardState();
310
+ pushFlowState(stack, labeledState('A', log), guards);
311
+ log.value = [] as never[];
164
312
  popFlowState(stack);
165
- expect(log).toEqual(['A.exit']);
313
+ expect(log.value).toEqual(['A.exit']);
166
314
  });
167
-
168
- it('does not throw when the popped state omits callbacks', () => {
315
+ it('does not panic when the popped state omits callbacks', () => {
169
316
  const stack = createFlowStack();
170
- stack.states.push({});
171
- expect(() => popFlowState(stack)).not.toThrow();
317
+ stack!.states.push(plain('A'));
318
+ expect(popFlowState(stack) !== null).toBe(true);
172
319
  });
173
320
  });
174
321
 
175
322
  describe('pushFlowState', () => {
176
323
  it('enters a state pushed onto an empty stack', () => {
177
- const log: string[] = [];
324
+ const log: { value: string[] } = { value: [] as never[] };
178
325
  const stack = createFlowStack();
179
- pushFlowState(stack, labeledState('A', log));
180
- expect(log).toEqual(['A.enter']);
326
+ const guards = guardState();
327
+ pushFlowState(stack, labeledState('A', log), guards);
328
+ expect(log.value).toEqual(['A.enter']);
181
329
  });
182
-
183
330
  it('pauses the previous top before entering the new state', () => {
184
- const log: string[] = [];
331
+ const log: { value: string[] } = { value: [] as never[] };
185
332
  const stack = createFlowStack();
186
- pushFlowState(stack, labeledState('A', log));
187
- log.length = 0;
188
- pushFlowState(stack, labeledState('B', log));
189
- expect(log).toEqual(['A.pause', 'B.enter']);
190
- expect(stack.states.length).toBe(2);
333
+ const guards = guardState();
334
+ pushFlowState(stack, labeledState('A', log), guards);
335
+ log.value = [] as never[];
336
+ pushFlowState(stack, labeledState('B', log), guards);
337
+ expect(log.value).toEqual(['A.pause', 'B.enter']);
338
+ expect(getFlowStackDepth(stack)).toEqual(2);
191
339
  });
192
-
193
- it('does not throw when the states omit lifecycle callbacks', () => {
340
+ it('does not panic when the states omit lifecycle callbacks', () => {
341
+ const stack = createFlowStack();
342
+ const guards = guardState();
343
+ pushFlowState(stack, plain('A'), guards);
344
+ pushFlowState(stack, plain('B'), guards);
345
+ expect(getFlowStackDepth(stack)).toEqual(2);
346
+ });
347
+ it('supports a real reentrant push from on enter', () => {
348
+ const log: { value: string[] } = { value: [] as never[] };
194
349
  const stack = createFlowStack();
195
- pushFlowState(stack, {});
196
- expect(() => pushFlowState(stack, {})).not.toThrow();
197
- expect(stack.states.length).toBe(2);
350
+ const guards = guardState();
351
+ const nestedLog = log;
352
+ const nestedStack = stack;
353
+ const nestedGuards = guards;
354
+ let a: FlowState = {
355
+ name: 'A',
356
+ onEnter: undefined,
357
+ onExit: undefined,
358
+ onPause: undefined,
359
+ onResume: undefined,
360
+ onUpdate: undefined,
361
+ renderBelow: undefined,
362
+ updateBelow: undefined,
363
+ };
364
+ a.onEnter = () => {
365
+ nestedLog.value.push('A.enter');
366
+ const b = state({
367
+ name: 'B',
368
+ onEnter: (() => {
369
+ const inner = nestedLog;
370
+ return () => inner.value.push('B.enter');
371
+ })(),
372
+ onExit: undefined,
373
+ onPause: undefined,
374
+ onResume: undefined,
375
+ onUpdate: undefined,
376
+ renderBelow: undefined,
377
+ updateBelow: undefined,
378
+ });
379
+ pushFlowState(nestedStack, b, nestedGuards);
380
+ };
381
+ pushFlowState(stack, state(a), guards);
382
+ expect(log.value).toEqual(['A.enter', 'B.enter']);
383
+ expect(getFlowStackDepth(stack)).toEqual(2);
384
+ expect(guards!.transitionDepth).toEqual(0);
385
+ });
386
+ it('supports a real reentrant push from on pause', () => {
387
+ const stack = createFlowStack();
388
+ const guards = guardState();
389
+ const stackForPause = stack;
390
+ const guardsForPause = guards;
391
+ const pausedOnce: { value: boolean[] } = { value: [] as never[] };
392
+ const pausedOnceSlot = pausedOnce;
393
+ let a: FlowState = {
394
+ name: 'A',
395
+ onEnter: undefined,
396
+ onExit: undefined,
397
+ onPause: undefined,
398
+ onResume: undefined,
399
+ onUpdate: undefined,
400
+ renderBelow: undefined,
401
+ updateBelow: undefined,
402
+ };
403
+ a.onPause = () => {
404
+ if (takeOnce(pausedOnceSlot)) {
405
+ pushFlowState(stackForPause, plain('C'), guardsForPause);
406
+ }
407
+ };
408
+ pushFlowState(stack, state(a), guards);
409
+ pushFlowState(stack, plain('B'), guards);
410
+ const states = stack!;
411
+ expect(states.states.length).toEqual(3);
412
+ expect(states.states[0]!.name).toEqual('A');
413
+ expect(states.states[1]!.name).toEqual('C');
414
+ expect(states.states[2]!.name).toEqual('B');
415
+ expect(guards!.transitionDepth).toEqual(0);
198
416
  });
199
417
  });
200
418
 
201
419
  describe('replaceFlowState', () => {
202
420
  it('exits the top and enters the replacement without touching the state below', () => {
203
- const log: string[] = [];
421
+ const log: { value: string[] } = { value: [] as never[] };
204
422
  const stack = createFlowStack();
423
+ const guards = guardState();
205
424
  const a = labeledState('A', log);
206
- pushFlowState(stack, a);
207
- pushFlowState(stack, labeledState('B', log));
208
- log.length = 0;
209
- replaceFlowState(stack, labeledState('C', log));
210
- expect(log).toEqual(['B.exit', 'C.enter']);
211
- expect(stack.states.length).toBe(2);
212
- expect(stack.states[0]).toBe(a);
425
+ pushFlowState(stack, a, guards);
426
+ pushFlowState(stack, labeledState('B', log), guards);
427
+ log.value = [] as never[];
428
+ replaceFlowState(stack, labeledState('C', log), guards);
429
+ expect(log.value).toEqual(['B.exit', 'C.enter']);
430
+ expect(getFlowStackDepth(stack)).toEqual(2);
431
+ expect(stack!.states[0] === a).toBe(true);
213
432
  });
214
-
215
433
  it('just pushes and enters on an empty stack', () => {
216
- const log: string[] = [];
434
+ const log: { value: string[] } = { value: [] as never[] };
217
435
  const stack = createFlowStack();
218
- replaceFlowState(stack, labeledState('C', log));
219
- expect(log).toEqual(['C.enter']);
220
- expect(stack.states.length).toBe(1);
436
+ const guards = guardState();
437
+ replaceFlowState(stack, labeledState('C', log), guards);
438
+ expect(log.value).toEqual(['C.enter']);
439
+ expect(getFlowStackDepth(stack)).toEqual(1);
221
440
  });
222
-
223
- it('does not throw when states omit callbacks', () => {
441
+ it('does not panic when the states omit callbacks', () => {
224
442
  const stack = createFlowStack();
225
- stack.states.push({});
226
- expect(() => replaceFlowState(stack, {})).not.toThrow();
443
+ stack!.states.push(plain('A'));
444
+ const guards = guardState();
445
+ replaceFlowState(stack, plain('B'), guards);
446
+ expect(getFlowStackDepth(stack)).toEqual(1);
227
447
  });
228
448
  });
229
449
 
230
- function labeledState(name: string, log: string[], extra: Partial<FlowState> = {}): FlowState {
231
- return {
232
- name,
233
- onEnter: () => log.push(`${name}.enter`),
234
- onExit: () => log.push(`${name}.exit`),
235
- onPause: () => log.push(`${name}.pause`),
236
- onResume: () => log.push(`${name}.resume`),
237
- onUpdate: (deltaTime) => log.push(`${name}.update:${deltaTime}`),
238
- ...extra,
239
- };
240
- }
241
450
  describe('updateFlowStack', () => {
242
- it('ticks only the top with the frame deltaTime', () => {
243
- const log: string[] = [];
451
+ it('ticks only the top with the frame delta time', () => {
452
+ const log: { value: string[] } = { value: [] as never[] };
244
453
  const stack = createFlowStack();
245
- pushFlowState(stack, labeledState('A', log));
246
- pushFlowState(stack, labeledState('B', log));
247
- log.length = 0;
454
+ const guards = guardState();
455
+ pushFlowState(stack, labeledState('A', log), guards);
456
+ pushFlowState(stack, labeledState('B', log), guards);
457
+ log.value = [] as never[];
248
458
  updateFlowStack(stack, 0.016);
249
- expect(log).toEqual(['B.update:0.016']);
459
+ expect(log.value).toEqual(['B.update:0.016']);
250
460
  });
251
-
252
- it('ticks the state beneath a transparent updateBelow overlay', () => {
253
- const log: string[] = [];
461
+ it('ticks the state beneath a transparent update below overlay', () => {
462
+ const log: { value: string[] } = { value: [] as never[] };
254
463
  const stack = createFlowStack();
255
- pushFlowState(stack, labeledState('A', log));
256
- pushFlowState(stack, labeledState('B', log, { updateBelow: true }));
257
- log.length = 0;
464
+ const guards = guardState();
465
+ pushFlowState(stack, labeledState('A', log), guards);
466
+ let b = labeledState('B', log)!;
467
+ b.updateBelow = true;
468
+ pushFlowState(stack, state(b), guards);
469
+ log.value = [] as never[];
258
470
  updateFlowStack(stack, 0.02);
259
- expect(log).toEqual(['B.update:0.02', 'A.update:0.02']);
471
+ expect(log.value).toEqual(['B.update:0.02', 'A.update:0.02']);
260
472
  });
261
-
262
473
  it('does not tick below an opaque overlay', () => {
263
- const log: string[] = [];
474
+ const log: { value: string[] } = { value: [] as never[] };
264
475
  const stack = createFlowStack();
265
- pushFlowState(stack, labeledState('A', log));
266
- pushFlowState(stack, labeledState('B', log));
267
- log.length = 0;
476
+ const guards = guardState();
477
+ pushFlowState(stack, labeledState('A', log), guards);
478
+ pushFlowState(stack, labeledState('B', log), guards);
479
+ log.value = [] as never[];
268
480
  updateFlowStack(stack, 0.01);
269
- expect(log).toEqual(['B.update:0.01']);
481
+ expect(log.value).toEqual(['B.update:0.01']);
270
482
  });
271
-
272
- it('walks a chain of updateBelow overlays and stops at the first opaque one', () => {
273
- const log: string[] = [];
274
- const stack = createFlowStack();
275
- pushFlowState(stack, labeledState('A', log));
276
- pushFlowState(stack, labeledState('B', log));
277
- pushFlowState(stack, labeledState('C', log, { updateBelow: true }));
278
- pushFlowState(stack, labeledState('D', log, { updateBelow: true }));
279
- log.length = 0;
483
+ it('walks a chain of update below overlays and stops at the first opaque one', () => {
484
+ const log: { value: string[] } = { value: [] as never[] };
485
+ const stack = createFlowStack();
486
+ const guards = guardState();
487
+ pushFlowState(stack, labeledState('A', log), guards);
488
+ pushFlowState(stack, labeledState('B', log), guards);
489
+ let c = labeledState('C', log)!;
490
+ c.updateBelow = true;
491
+ pushFlowState(stack, state(c), guards);
492
+ let d = labeledState('D', log)!;
493
+ d.updateBelow = true;
494
+ pushFlowState(stack, state(d), guards);
495
+ log.value = [] as never[];
280
496
  updateFlowStack(stack, 0.5);
281
- expect(log).toEqual(['D.update:0.5', 'C.update:0.5', 'B.update:0.5']);
497
+ expect(log.value).toEqual(['D.update:0.5', 'C.update:0.5', 'B.update:0.5']);
282
498
  });
283
-
284
- it('is a no-op on an empty stack', () => {
499
+ it('is a no op on an empty stack', () => {
285
500
  const stack = createFlowStack();
286
- expect(() => updateFlowStack(stack, 0.016)).not.toThrow();
501
+ updateFlowStack(stack, 0.016);
287
502
  });
288
-
289
- it('does not throw when a ticked state omits onUpdate', () => {
503
+ it('does not panic when a ticked state omits on update', () => {
504
+ const stack = createFlowStack();
505
+ stack!.states.push(
506
+ state({
507
+ name: 'lower',
508
+ onEnter: undefined,
509
+ onExit: undefined,
510
+ onPause: undefined,
511
+ onResume: undefined,
512
+ onUpdate: undefined,
513
+ renderBelow: undefined,
514
+ updateBelow: true,
515
+ }),
516
+ );
517
+ stack!.states.push(plain('top'));
518
+ updateFlowStack(stack, 0.016);
519
+ });
520
+ it('snapshots the stack before a reentrant update clears it', () => {
521
+ const calls: { value: string[] } = { value: [] as never[] };
290
522
  const stack = createFlowStack();
291
- stack.states.push({ updateBelow: true }, {});
292
- expect(() => updateFlowStack(stack, 0.016)).not.toThrow();
523
+ const lowerCalls = calls;
524
+ stack!.states.push(
525
+ state({
526
+ name: 'lower',
527
+ onEnter: undefined,
528
+ onExit: undefined,
529
+ onPause: undefined,
530
+ onResume: undefined,
531
+ onUpdate: (_deltaTime: number) => {
532
+ lowerCalls.value.push('lower');
533
+ },
534
+ renderBelow: undefined,
535
+ updateBelow: undefined,
536
+ }),
537
+ );
538
+ const topCalls = calls;
539
+ const topStack = stack;
540
+ stack!.states.push(
541
+ state({
542
+ name: 'top',
543
+ onEnter: undefined,
544
+ onExit: undefined,
545
+ onPause: undefined,
546
+ onResume: undefined,
547
+ onUpdate: (_deltaTime: number) => {
548
+ topCalls.value.push('top');
549
+ clearFlowStack(topStack);
550
+ },
551
+ renderBelow: undefined,
552
+ updateBelow: true,
553
+ }),
554
+ );
555
+ updateFlowStack(stack, 0.016);
556
+ expect(calls.value).toEqual(['top', 'lower']);
557
+ expect(getFlowStackDepth(stack)).toEqual(0);
293
558
  });
294
559
  });