@g9tm/app-diagnostic 0.2.0 → 0.2.2

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/src/recording.ts CHANGED
@@ -1,176 +1,176 @@
1
- // One recorder's life as the tester sees it — the TypeScript twin of G9AppDiagnostic.Client RecordingSession
2
- // (diagnostic/AiGuides/02-Tester-Mode.md «The stop button»): a single button that starts and stops it and never swallows
3
- // a tap. A Stop used to be lost three ways: a tap while the start was still running was dropped by a busy guard; a tap
4
- // within a throttle window after the start was dropped too; and a recorder whose stop never returned left the button on
5
- // Stop for good. Here:
6
- // - a stop asked for while Starting is remembered and done the moment the start finishes;
7
- // - a stop while Stopping is answered by the one in flight (never a second recording);
8
- // - a stop has a time limit: past it the session is Idle again, the late result is dropped, `onStopTimedOut` says so;
9
- // - a start or stop that throws ends Idle, never stuck.
10
- // Every method may be called at any time; none of them rejects.
11
-
12
- export type RecordingState = 'idle' | 'starting' | 'recording' | 'stopping';
13
-
14
- export interface RecordingSessionOptions<T> {
15
- /** Starts the recorder; false = it could not (the session goes back to Idle). */
16
- readonly start: () => Promise<boolean>;
17
- /** Stops it and returns what it made (null = nothing usable). */
18
- readonly stop: () => Promise<T | null>;
19
- /** What happens with the result (attach it); `timedOut` when the stop did not return in time. */
20
- readonly finished: (result: T | null, timedOut: boolean) => Promise<void> | void;
21
- /** How long a stop may take before the session gives up on it (MAUI: 30 s screen, 10 s voice). */
22
- readonly stopTimeoutMs: number;
23
- readonly onStateChanged?: (state: RecordingState) => void;
24
- readonly onStopTimedOut?: () => void;
25
- readonly onFaulted?: (error: unknown) => void;
26
- readonly now?: () => number;
27
- }
28
-
29
- export class RecordingSession<T> {
30
- private readonly o: RecordingSessionOptions<T>;
31
- private stateValue: RecordingState = 'idle';
32
- private stopRequested = false;
33
- private startedAt: number | null = null;
34
- private inFlight: Promise<void> = Promise.resolve();
35
-
36
- constructor(options: RecordingSessionOptions<T>) {
37
- this.o = options;
38
- }
39
-
40
- get state(): RecordingState {
41
- return this.stateValue;
42
- }
43
-
44
- /** Starting, recording or stopping: the button is the way to end it. */
45
- get isActive(): boolean {
46
- return this.stateValue !== 'idle';
47
- }
48
-
49
- /** When the recorder actually started (ms), or null while it is not recording. */
50
- get startedAtMs(): number | null {
51
- return this.startedAt;
52
- }
53
-
54
- /** The button: starts when idle, stops when recording, stops as soon as it can while starting. */
55
- toggle(): Promise<void> {
56
- switch (this.stateValue) {
57
- case 'idle':
58
- this.stopRequested = false;
59
- this.set('starting');
60
- return this.track(this.startCore());
61
- case 'starting':
62
- this.stopRequested = true;
63
- return Promise.resolve();
64
- case 'recording':
65
- this.set('stopping');
66
- return this.track(this.stopCore());
67
- default:
68
- return Promise.resolve(); // already stopping: the tap is answered by the stop in flight
69
- }
70
- }
71
-
72
- /** Stop if anything runs (the recorder ended by itself, the panel goes away). Idle: nothing. */
73
- stop(): Promise<void> {
74
- switch (this.stateValue) {
75
- case 'starting':
76
- this.stopRequested = true;
77
- return Promise.resolve();
78
- case 'recording':
79
- this.set('stopping');
80
- return this.track(this.stopCore());
81
- default:
82
- return Promise.resolve();
83
- }
84
- }
85
-
86
- /**
87
- * A recorder that is already running (it outlived a reload of the app's script): the session takes it over as
88
- * Recording, so the next tap stops it and keeps its file. Only from Idle.
89
- */
90
- adopt(startedAtMs: number = (this.o.now ?? Date.now)()): boolean {
91
- if (this.stateValue !== 'idle') return false;
92
- this.startedAt = startedAtMs;
93
- this.set('recording');
94
- return true;
95
- }
96
-
97
- /** Resolves when whatever the session is doing now has finished (tests, a send that must wait for the file). */
98
- settled(): Promise<void> {
99
- return this.inFlight;
100
- }
101
-
102
- private track(p: Promise<void>): Promise<void> {
103
- this.inFlight = p;
104
- return p;
105
- }
106
-
107
- private async startCore(): Promise<void> {
108
- let started = false;
109
- try {
110
- started = await this.o.start();
111
- } catch (error) {
112
- started = false;
113
- this.fault(error);
114
- }
115
- if (!started) {
116
- this.stopRequested = false;
117
- this.set('idle');
118
- return;
119
- }
120
- this.startedAt = (this.o.now ?? Date.now)();
121
- const stopNow = this.stopRequested;
122
- this.stopRequested = false;
123
- this.set(stopNow ? 'stopping' : 'recording');
124
- if (stopNow) await this.stopCore();
125
- }
126
-
127
- private async stopCore(): Promise<void> {
128
- let result: T | null = null;
129
- let timedOut = false;
130
- const clock: { timer?: ReturnType<typeof setTimeout> } = {};
131
- try {
132
- const stopping = this.o.stop();
133
- const limit = new Promise<'timeout'>((resolve) => {
134
- clock.timer = setTimeout(() => resolve('timeout'), this.o.stopTimeoutMs);
135
- });
136
- const first = await Promise.race([stopping.then((r) => ({ r })), limit]);
137
- if (first === 'timeout') {
138
- timedOut = true;
139
- // The late result is dropped, its failure still observed (no unhandled rejection).
140
- stopping.catch(() => {});
141
- } else {
142
- result = first.r;
143
- }
144
- } catch (error) {
145
- this.fault(error);
146
- } finally {
147
- if (clock.timer !== undefined) clearTimeout(clock.timer);
148
- }
149
- this.startedAt = null;
150
- this.set('idle');
151
- if (timedOut) this.safe(() => this.o.onStopTimedOut?.());
152
- try {
153
- await this.o.finished(result, timedOut);
154
- } catch (error) {
155
- this.fault(error);
156
- }
157
- }
158
-
159
- private set(state: RecordingState): void {
160
- if (this.stateValue === state) return;
161
- this.stateValue = state;
162
- this.safe(() => this.o.onStateChanged?.(state));
163
- }
164
-
165
- private fault(error: unknown): void {
166
- this.safe(() => this.o.onFaulted?.(error));
167
- }
168
-
169
- private safe(fn: () => void): void {
170
- try {
171
- fn();
172
- } catch {
173
- // a listener's throw never breaks the button
174
- }
175
- }
176
- }
1
+ // One recorder's life as the tester sees it — the TypeScript twin of G9AppDiagnostic.Client RecordingSession
2
+ // (diagnostic/AiGuides/02-Tester-Mode.md «The stop button»): a single button that starts and stops it and never swallows
3
+ // a tap. A Stop used to be lost three ways: a tap while the start was still running was dropped by a busy guard; a tap
4
+ // within a throttle window after the start was dropped too; and a recorder whose stop never returned left the button on
5
+ // Stop for good. Here:
6
+ // - a stop asked for while Starting is remembered and done the moment the start finishes;
7
+ // - a stop while Stopping is answered by the one in flight (never a second recording);
8
+ // - a stop has a time limit: past it the session is Idle again, the late result is dropped, `onStopTimedOut` says so;
9
+ // - a start or stop that throws ends Idle, never stuck.
10
+ // Every method may be called at any time; none of them rejects.
11
+
12
+ export type RecordingState = 'idle' | 'starting' | 'recording' | 'stopping';
13
+
14
+ export interface RecordingSessionOptions<T> {
15
+ /** Starts the recorder; false = it could not (the session goes back to Idle). */
16
+ readonly start: () => Promise<boolean>;
17
+ /** Stops it and returns what it made (null = nothing usable). */
18
+ readonly stop: () => Promise<T | null>;
19
+ /** What happens with the result (attach it); `timedOut` when the stop did not return in time. */
20
+ readonly finished: (result: T | null, timedOut: boolean) => Promise<void> | void;
21
+ /** How long a stop may take before the session gives up on it (MAUI: 30 s screen, 10 s voice). */
22
+ readonly stopTimeoutMs: number;
23
+ readonly onStateChanged?: (state: RecordingState) => void;
24
+ readonly onStopTimedOut?: () => void;
25
+ readonly onFaulted?: (error: unknown) => void;
26
+ readonly now?: () => number;
27
+ }
28
+
29
+ export class RecordingSession<T> {
30
+ private readonly o: RecordingSessionOptions<T>;
31
+ private stateValue: RecordingState = 'idle';
32
+ private stopRequested = false;
33
+ private startedAt: number | null = null;
34
+ private inFlight: Promise<void> = Promise.resolve();
35
+
36
+ constructor(options: RecordingSessionOptions<T>) {
37
+ this.o = options;
38
+ }
39
+
40
+ get state(): RecordingState {
41
+ return this.stateValue;
42
+ }
43
+
44
+ /** Starting, recording or stopping: the button is the way to end it. */
45
+ get isActive(): boolean {
46
+ return this.stateValue !== 'idle';
47
+ }
48
+
49
+ /** When the recorder actually started (ms), or null while it is not recording. */
50
+ get startedAtMs(): number | null {
51
+ return this.startedAt;
52
+ }
53
+
54
+ /** The button: starts when idle, stops when recording, stops as soon as it can while starting. */
55
+ toggle(): Promise<void> {
56
+ switch (this.stateValue) {
57
+ case 'idle':
58
+ this.stopRequested = false;
59
+ this.set('starting');
60
+ return this.track(this.startCore());
61
+ case 'starting':
62
+ this.stopRequested = true;
63
+ return Promise.resolve();
64
+ case 'recording':
65
+ this.set('stopping');
66
+ return this.track(this.stopCore());
67
+ default:
68
+ return Promise.resolve(); // already stopping: the tap is answered by the stop in flight
69
+ }
70
+ }
71
+
72
+ /** Stop if anything runs (the recorder ended by itself, the panel goes away). Idle: nothing. */
73
+ stop(): Promise<void> {
74
+ switch (this.stateValue) {
75
+ case 'starting':
76
+ this.stopRequested = true;
77
+ return Promise.resolve();
78
+ case 'recording':
79
+ this.set('stopping');
80
+ return this.track(this.stopCore());
81
+ default:
82
+ return Promise.resolve();
83
+ }
84
+ }
85
+
86
+ /**
87
+ * A recorder that is already running (it outlived a reload of the app's script): the session takes it over as
88
+ * Recording, so the next tap stops it and keeps its file. Only from Idle.
89
+ */
90
+ adopt(startedAtMs: number = (this.o.now ?? Date.now)()): boolean {
91
+ if (this.stateValue !== 'idle') return false;
92
+ this.startedAt = startedAtMs;
93
+ this.set('recording');
94
+ return true;
95
+ }
96
+
97
+ /** Resolves when whatever the session is doing now has finished (tests, a send that must wait for the file). */
98
+ settled(): Promise<void> {
99
+ return this.inFlight;
100
+ }
101
+
102
+ private track(p: Promise<void>): Promise<void> {
103
+ this.inFlight = p;
104
+ return p;
105
+ }
106
+
107
+ private async startCore(): Promise<void> {
108
+ let started = false;
109
+ try {
110
+ started = await this.o.start();
111
+ } catch (error) {
112
+ started = false;
113
+ this.fault(error);
114
+ }
115
+ if (!started) {
116
+ this.stopRequested = false;
117
+ this.set('idle');
118
+ return;
119
+ }
120
+ this.startedAt = (this.o.now ?? Date.now)();
121
+ const stopNow = this.stopRequested;
122
+ this.stopRequested = false;
123
+ this.set(stopNow ? 'stopping' : 'recording');
124
+ if (stopNow) await this.stopCore();
125
+ }
126
+
127
+ private async stopCore(): Promise<void> {
128
+ let result: T | null = null;
129
+ let timedOut = false;
130
+ const clock: { timer?: ReturnType<typeof setTimeout> } = {};
131
+ try {
132
+ const stopping = this.o.stop();
133
+ const limit = new Promise<'timeout'>((resolve) => {
134
+ clock.timer = setTimeout(() => resolve('timeout'), this.o.stopTimeoutMs);
135
+ });
136
+ const first = await Promise.race([stopping.then((r) => ({ r })), limit]);
137
+ if (first === 'timeout') {
138
+ timedOut = true;
139
+ // The late result is dropped, its failure still observed (no unhandled rejection).
140
+ stopping.catch(() => {});
141
+ } else {
142
+ result = first.r;
143
+ }
144
+ } catch (error) {
145
+ this.fault(error);
146
+ } finally {
147
+ if (clock.timer !== undefined) clearTimeout(clock.timer);
148
+ }
149
+ this.startedAt = null;
150
+ this.set('idle');
151
+ if (timedOut) this.safe(() => this.o.onStopTimedOut?.());
152
+ try {
153
+ await this.o.finished(result, timedOut);
154
+ } catch (error) {
155
+ this.fault(error);
156
+ }
157
+ }
158
+
159
+ private set(state: RecordingState): void {
160
+ if (this.stateValue === state) return;
161
+ this.stateValue = state;
162
+ this.safe(() => this.o.onStateChanged?.(state));
163
+ }
164
+
165
+ private fault(error: unknown): void {
166
+ this.safe(() => this.o.onFaulted?.(error));
167
+ }
168
+
169
+ private safe(fn: () => void): void {
170
+ try {
171
+ fn();
172
+ } catch {
173
+ // a listener's throw never breaks the button
174
+ }
175
+ }
176
+ }
package/src/store.ts CHANGED
@@ -1,39 +1,39 @@
1
- // A tiny observable value (get / set / subscribe): the package's state primitive. The same shape a ReactLynx app reads
2
- // with `useSyncExternalStore`, so a host's own `useStore(store)` works on these as they are.
3
-
4
- export type Listener = () => void;
5
-
6
- export interface ReadableStore<T> {
7
- get(): T;
8
- subscribe(listener: Listener): () => void;
9
- }
10
-
11
- export interface Store<T> extends ReadableStore<T> {
12
- set(next: T | ((previous: T) => T)): void;
13
- }
14
-
15
- export function createStore<T>(initial: T): Store<T> {
16
- let value = initial;
17
- const listeners = new Set<Listener>();
18
- return {
19
- get: () => value,
20
- set(next) {
21
- const resolved = typeof next === 'function' ? (next as (previous: T) => T)(value) : next;
22
- if (Object.is(resolved, value)) return;
23
- value = resolved;
24
- for (const listener of Array.from(listeners)) {
25
- try {
26
- listener();
27
- } catch {
28
- // a listener's throw never breaks the state
29
- }
30
- }
31
- },
32
- subscribe(listener) {
33
- listeners.add(listener);
34
- return () => {
35
- listeners.delete(listener);
36
- };
37
- },
38
- };
39
- }
1
+ // A tiny observable value (get / set / subscribe): the package's state primitive. The same shape a ReactLynx app reads
2
+ // with `useSyncExternalStore`, so a host's own `useStore(store)` works on these as they are.
3
+
4
+ export type Listener = () => void;
5
+
6
+ export interface ReadableStore<T> {
7
+ get(): T;
8
+ subscribe(listener: Listener): () => void;
9
+ }
10
+
11
+ export interface Store<T> extends ReadableStore<T> {
12
+ set(next: T | ((previous: T) => T)): void;
13
+ }
14
+
15
+ export function createStore<T>(initial: T): Store<T> {
16
+ let value = initial;
17
+ const listeners = new Set<Listener>();
18
+ return {
19
+ get: () => value,
20
+ set(next) {
21
+ const resolved = typeof next === 'function' ? (next as (previous: T) => T)(value) : next;
22
+ if (Object.is(resolved, value)) return;
23
+ value = resolved;
24
+ for (const listener of Array.from(listeners)) {
25
+ try {
26
+ listener();
27
+ } catch {
28
+ // a listener's throw never breaks the state
29
+ }
30
+ }
31
+ },
32
+ subscribe(listener) {
33
+ listeners.add(listener);
34
+ return () => {
35
+ listeners.delete(listener);
36
+ };
37
+ },
38
+ };
39
+ }