@katn30/trakr 3.0.0 → 4.0.0

package/README.md

@@ -1579,6 +1579,76 @@ Given `issue.stage = 'InAnalysis'` and `issue.analysisSummary = 'AS'`, `generate
 
 Subclass `@EventTracked` fields appear **after** base-class fields, matching the declaration order across the prototype chain.
 
+### Scalars vs. sequences: choosing the primitive
+
+`@EventTracked` and `EventTrackedCollection` look interchangeable when both can carry the same field on the wire — a `stage` property could sit on the model as either an accessor or an item in a collection. They are **not** interchangeable: they encode different semantics, and picking the wrong one silently loses information at Save time.
+
+**`@EventTracked` accessor — the field is a *value*.** Multiple writes in one session collapse to **one** event carrying the field's **final** value. That is correct behaviour: consumers care about "what the field is now", not "how many times the user retyped it". Typing `Faulty widget` character by character produces one `SubmittedDetailsRevised{name: 'Faulty widget'}`, not eleven.
+
+**`EventTrackedCollection` — the field is a *sequence of actions*.** Each push emits its own `itemAdded` event, in insertion order. Two pushes produce two events; they never collapse.
+
+The trap: state-machine-style fields *look* like scalars ("current stage"), so it is tempting to model them as `@EventTracked accessor stage`. That is wrong. A transition is not an update to a value — it is a discrete action, and every intermediate state must be persisted for the backend's transition preconditions (`from → to` allowed?) to hold on replay.
+
+```typescript
+// WRONG — accessor collapses "Submitted → InAnalysis → InFixing" into one event
+class IssueModel extends TrackedObject {
+  @EventTracked(IssueEvents.StageTransitioned) accessor stage: string = 'Submitted';
+}
+
+issue.stage = 'InAnalysis';
+issue.stage = 'InFixing';
+
+// generateEvents() returns ONE event with the final value:
+// [{ eventType: 'StageTransitioned', payload: { stage: 'InFixing' } }]
+// Backend replays: Submitted → InFixing, rejects as illegal transition.
+```
+
+```typescript
+// RIGHT — one StageTransitioned event per push, in order
+class StageTransition extends TrackedObject {
+  @EventTracked(IssueEvents.StageTransitioned) accessor stage: string;
+  transitionedAt: string;
+  transitionedBy: string | null;
+
+  constructor(t: Tracker, stage: string, at: string, by: string | null) {
+    super(t);
+    this.stage = stage;
+    this.transitionedAt = at;
+    this.transitionedBy = by;
+  }
+}
+
+class IssueModel extends TrackedObject {
+  stage: string = 'Submitted';                          // plain field, drives UI only
+  readonly transitions: EventTrackedCollection<StageTransition>;
+
+  constructor(t: Tracker) {
+    super(t);
+    this.transitions = new EventTrackedCollection<StageTransition>(
+      t, [], undefined, { itemAdded: IssueEvents.StageTransitioned },
+    );
+  }
+
+  transitionTo(target: string, by: string | null): void {
+    this.stage = target;
+    this.transitions.push(
+      this.tracker.construct(() => new StageTransition(this.tracker, target, new Date().toISOString(), by)),
+    );
+  }
+}
+
+issue.transitionTo('InAnalysis', 'alice');
+issue.transitionTo('InFixing', 'alice');
+
+// generateEvents() returns TWO events, in insertion order:
+// [
+//   { eventType: 'StageTransitioned', payload: { stage: 'InAnalysis' }, ... },
+//   { eventType: 'StageTransitioned', payload: { stage: 'InFixing' },   ... },
+// ]
+```
+
+**Rule of thumb.** If the field's meaning is *"what it is now"* and the backend does not need to see every intermediate write, use `@EventTracked` on an accessor. If each write is a *distinct, ordered action* the backend must apply sequentially — state transitions, audit log entries, phase changes, workflow steps — use `EventTrackedCollection` with an `itemAdded` tag.
+
 ### Migration
 
 There is **nothing to migrate** from v2 → v3 for existing code. `Tracker`, `TrackedObject`, `TrackedCollection`, `@Tracked`, and `@AutoId` are unchanged. Opt in per class or per collection whenever the consumer needs event generation. A single tracker instance can mix event-tracked and non-event-tracked objects.