@flighthq/flow 0.5.1-next.920.da8f530 → 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 +176 -71
  15. package/dist/flow.js.map +1 -1
  16. package/dist/flowGuards.d.ts +23 -0
  17. package/dist/flowGuards.d.ts.map +1 -0
  18. package/dist/flowGuards.js +78 -0
  19. package/dist/flowGuards.js.map +1 -0
  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 -1
  33. package/dist/index.d.ts.map +1 -1
  34. package/dist/index.js +4 -1
  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 -4
  41. package/src/flow.test.ts +440 -175
  42. package/src/flowGuards.test.ts +146 -0
  43. package/src/flowStackCompat.test.ts +99 -0
  44. package/src/flowTransitions.test.ts +26 -0
@@ -0,0 +1,146 @@
1
+ // Generated from crates/flight-flow/tests/flow_guards_test.rs by flight-compiler.
2
+ // Rust is authoritative; run `npm run generate` after changing it.
3
+
4
+ import { addLogSink, createJsonLogFormatter, createLogState } from '@flighthq/log/contract';
5
+ import type { LogStateRaw } from '@flighthq/log/contract';
6
+ import { describe, expect, it } from 'vitest';
7
+
8
+ import {
9
+ createFlowStack,
10
+ disableFlowGuards,
11
+ enableFlowGuards,
12
+ getFlowGuardKindString,
13
+ parseFlowGuardKind,
14
+ pushFlowState,
15
+ reportFlowGuard,
16
+ } from './contract.ts';
17
+ import type { FlowGuardContext, FlowGuardState, FlowGuardStateRef, FlowState } from './contract.ts';
18
+
19
+ function guardState(): FlowGuardStateRef {
20
+ const state = { enabled: false, transitionDepth: 0, context: { logState: logState(), clock: () => 0.0 } };
21
+ disableFlowGuards(state);
22
+ return state;
23
+ }
24
+
25
+ function logState(): LogStateRaw {
26
+ return createLogState();
27
+ }
28
+
29
+ function captureFormattedEntries(state: LogStateRaw): { value: string[] } {
30
+ const entries: { value: string[] } = { value: [] as never[] };
31
+ const captured = entries;
32
+ const formatter = createJsonLogFormatter(state);
33
+ addLogSink(state, (entry) => {
34
+ captured.value.push(formatter(entry));
35
+ });
36
+ return entries;
37
+ }
38
+
39
+ function plain(name: string): FlowState {
40
+ return {
41
+ name: String(name),
42
+ onEnter: undefined,
43
+ onExit: undefined,
44
+ onPause: undefined,
45
+ onResume: undefined,
46
+ onUpdate: undefined,
47
+ renderBelow: undefined,
48
+ updateBelow: undefined,
49
+ };
50
+ }
51
+
52
+ describe('disableFlowGuards', () => {
53
+ it('is idempotent', () => {
54
+ const guards = guardState();
55
+ disableFlowGuards(guards);
56
+ disableFlowGuards(guards);
57
+ expect(!guards!.enabled).toBe(true);
58
+ });
59
+ });
60
+
61
+ describe('enableFlowGuards', () => {
62
+ it('toggles the opt in guard and captures the enable time context', () => {
63
+ const guards = guardState();
64
+ const state = logState();
65
+ enableFlowGuards(guards, state, () => 0.0);
66
+ expect(guards!.enabled).toBe(true);
67
+ expect(guards!.context !== null).toBe(true);
68
+ disableFlowGuards(guards);
69
+ expect(!guards!.enabled).toBe(true);
70
+ });
71
+ });
72
+
73
+ describe('getFlowGuardKindString', () => {
74
+ it('returns the exact ts string for each kind', () => {
75
+ expect(getFlowGuardKindString('duplicate-state-push')).toEqual('duplicate-state-push');
76
+ expect(getFlowGuardKindString('transition-during-transition')).toEqual('transition-during-transition');
77
+ });
78
+ });
79
+
80
+ describe('parseFlowGuardKind', () => {
81
+ it('parses the exact ts strings and returns none for unknown names', () => {
82
+ expect(parseFlowGuardKind('duplicate-state-push')).toEqual('duplicate-state-push');
83
+ expect(parseFlowGuardKind('transition-during-transition')).toEqual('transition-during-transition');
84
+ expect(parseFlowGuardKind('nope') ?? 'duplicate-state-push').toEqual('duplicate-state-push');
85
+ });
86
+ });
87
+
88
+ describe('reportFlowGuard', () => {
89
+ it('logs a warn entry with the exact kind string and live clock time when enabled', () => {
90
+ const guards = guardState();
91
+ const state = logState();
92
+ enableFlowGuards(guards, state, () => 42.0);
93
+ const captured = captureFormattedEntries(state);
94
+ reportFlowGuard(guards, 'duplicate-state-push');
95
+ const entries = captured.value;
96
+ expect(entries.length).toEqual(1);
97
+ expect(entries[0].includes('"t":42')).toBe(true);
98
+ expect(entries[0].includes('"level":"warn"')).toBe(true);
99
+ expect(entries[0].includes('"channel":"flow"')).toBe(true);
100
+ expect(entries[0].includes('"kind":"duplicate-state-push"')).toBe(true);
101
+ });
102
+ it('is a no op when guards are disabled', () => {
103
+ const guards = guardState();
104
+ const state = logState();
105
+ const captured = captureFormattedEntries(state);
106
+ reportFlowGuard(guards, 'transition-during-transition');
107
+ expect(captured.value.length === 0).toBe(true);
108
+ });
109
+ it('transition during transition is reported when the guard depth is already positive', () => {
110
+ const guards = guardState();
111
+ const state = logState();
112
+ enableFlowGuards(guards, state, () => 3.0);
113
+ guards!.transitionDepth = 1;
114
+ const captured = captureFormattedEntries(state);
115
+ const stack = createFlowStack();
116
+ pushFlowState(stack, plain('A'), guards);
117
+ const entries = captured.value;
118
+ expect(entries.length).toEqual(1);
119
+ expect(entries[0].includes('"t":3')).toBe(true);
120
+ expect(entries[0].includes('"kind":"transition-during-transition"')).toBe(true);
121
+ expect(guards!.transitionDepth).toEqual(1);
122
+ });
123
+ it('duplicate state push is reported by shared state identity', () => {
124
+ const guards = guardState();
125
+ const state = logState();
126
+ enableFlowGuards(guards, state, () => 0.0);
127
+ const captured = captureFormattedEntries(state);
128
+ const stack = createFlowStack();
129
+ const a = plain('A');
130
+ pushFlowState(stack, a, guards);
131
+ pushFlowState(stack, a, guards);
132
+ const entries = captured.value;
133
+ expect(entries.length).toEqual(1);
134
+ expect(entries[0].includes('"kind":"duplicate-state-push"')).toBe(true);
135
+ });
136
+ it('equal but distinct states are not a duplicate', () => {
137
+ const guards = guardState();
138
+ const state = logState();
139
+ enableFlowGuards(guards, state, () => 0.0);
140
+ const captured = captureFormattedEntries(state);
141
+ const stack = createFlowStack();
142
+ pushFlowState(stack, plain('A'), guards);
143
+ pushFlowState(stack, plain('A'), guards);
144
+ expect(captured.value.length === 0).toBe(true);
145
+ });
146
+ });
@@ -0,0 +1,99 @@
1
+ import { Entity } from '@flighthq/entity/contract';
2
+
3
+ import {
4
+ createFlowStack,
5
+ getActiveFlowState,
6
+ getFlowStackDepth,
7
+ getFlowStackVisibleStates,
8
+ popFlowState,
9
+ } from './flow.ts';
10
+ import { FlowStack } from './flowStackCompat.ts';
11
+ import type { FlowState } from './flowTypes.ts';
12
+ import type { FlowGuardState } from './types.ts';
13
+
14
+ describe('FlowStack', () => {
15
+ it('provides class-correct constructor and create defaults compatible with Entity', () => {
16
+ const constructed = new FlowStack();
17
+ const created = FlowStack.create();
18
+ const entityClass: typeof Entity = FlowStack;
19
+ const baseCreated = entityClass.create();
20
+
21
+ expect(constructed).toBeInstanceOf(FlowStack);
22
+ expect(constructed.raw.states).toEqual([]);
23
+ expect(created).toBeInstanceOf(FlowStack);
24
+ expect(created.raw.states).toEqual([]);
25
+ expect(baseCreated).toBeInstanceOf(FlowStack);
26
+ expectTypeOf(constructed).toEqualTypeOf<FlowStack>();
27
+ expectTypeOf(created).toEqualTypeOf<FlowStack>();
28
+ expectTypeOf(baseCreated).toEqualTypeOf<Entity>();
29
+ });
30
+
31
+ it('returns one stable typed wrapper without replacing the raw stack identity', () => {
32
+ const raw = createFlowStack();
33
+ const wrapper = FlowStack.from(raw);
34
+
35
+ expect(wrapper.raw).toBe(raw);
36
+ expect(FlowStack.from(raw)).toBe(wrapper);
37
+ expect(Entity.from(raw)).toBe(wrapper);
38
+ });
39
+
40
+ it('rejects generic-first and incompatible typed-wrapper collisions', () => {
41
+ const genericRaw = createFlowStack();
42
+ const generic = Entity.from(genericRaw);
43
+
44
+ expect(() => FlowStack.from(genericRaw)).toThrow(
45
+ new TypeError('FlowStackRaw is already attached to an incompatible OOP wrapper'),
46
+ );
47
+ expect(Entity.from(genericRaw)).toBe(generic);
48
+
49
+ const typedRaw = createFlowStack();
50
+ const other = new OtherEntity(typedRaw);
51
+ expect(() => FlowStack.from(typedRaw)).toThrow(TypeError);
52
+ expect(Entity.from(typedRaw)).toBe(other);
53
+ });
54
+
55
+ it('delegates method sugar to the same raw stack as the free functions', () => {
56
+ const stack = FlowStack.create();
57
+ const guards = guardState();
58
+ const calls: string[] = [];
59
+ const lower: FlowState = { name: 'lower', onUpdate: () => calls.push('lower') };
60
+ const top: FlowState = {
61
+ name: 'top',
62
+ onUpdate: () => calls.push('top'),
63
+ renderBelow: true,
64
+ updateBelow: true,
65
+ };
66
+
67
+ stack.pushState(lower, guards);
68
+ stack.pushState(top, guards);
69
+ expect(stack.states).toBe(stack.raw.states);
70
+ expect(stack.activeState()).toBe(getActiveFlowState(stack.raw));
71
+ expect(stack.stackDepth()).toBe(getFlowStackDepth(stack.raw));
72
+
73
+ const viaMethod: FlowState[] = [];
74
+ const viaFree: FlowState[] = [];
75
+ stack.visibleStates(viaMethod);
76
+ getFlowStackVisibleStates(viaFree, stack.raw);
77
+ expect(viaMethod).toEqual(viaFree);
78
+
79
+ stack.updateStack(0.016);
80
+ expect(calls).toEqual(['top', 'lower']);
81
+
82
+ const replacement: FlowState = { name: 'replacement' };
83
+ stack.replaceState(replacement, guards);
84
+ expect(getActiveFlowState(stack.raw)).toBe(replacement);
85
+ expect(stack.popState()).toBe(replacement);
86
+ expect(popFlowState(stack.raw)).toBe(lower);
87
+ expect(stack.popState()).toBeNull();
88
+
89
+ stack.pushState(lower, guards);
90
+ stack.clearStack();
91
+ expect(getFlowStackDepth(stack.raw)).toBe(0);
92
+ });
93
+ });
94
+
95
+ class OtherEntity extends Entity {}
96
+
97
+ function guardState(): FlowGuardState {
98
+ return { context: null, enabled: false, transitionDepth: 0 };
99
+ }
@@ -0,0 +1,26 @@
1
+ import { describe, expect, it } from 'vitest';
2
+
3
+ import { createFlowStack, pushFlowState, replaceFlowState } from './flow.ts';
4
+ import type { FlowGuardState } from './types.ts';
5
+
6
+ function guardState(): FlowGuardState {
7
+ return { context: null, enabled: false, transitionDepth: 0 };
8
+ }
9
+
10
+ function failOnEnter(): never {
11
+ throw new Error('onEnter failed');
12
+ }
13
+
14
+ describe('runFlowTransition', () => {
15
+ it('restores transition depth when pushFlowState callbacks throw', () => {
16
+ const guards = guardState();
17
+ expect(() => pushFlowState(createFlowStack(), { onEnter: failOnEnter }, guards)).toThrow('onEnter failed');
18
+ expect(guards.transitionDepth).toBe(0);
19
+ });
20
+
21
+ it('restores transition depth when replaceFlowState callbacks throw', () => {
22
+ const guards = guardState();
23
+ expect(() => replaceFlowState(createFlowStack(), { onEnter: failOnEnter }, guards)).toThrow('onEnter failed');
24
+ expect(guards.transitionDepth).toBe(0);
25
+ });
26
+ });