@katn30/trakr 3.0.0 → 4.1.0

package/README.md

@@ -610,6 +610,14 @@ tracker.onCommit(keys);       // same, plus write real server IDs to @AutoId fie
 2. Transitions every tracked object's `state` to `Unchanged` and resets `dirtyCounter`.
 3. Appends the state change into the existing last undo operation — so undo atomically reverts both the user's edits and the committed state together (no spurious extra undo steps).
 
+**Lookup by trackingId**
+
+```typescript
+const obj = tracker.getByTrackingId(42);   // TrackedObject | undefined
+```
+
+Returns the tracked object whose `trackingId` matches the given value, or `undefined` if none. Deleted objects are still findable this way (they remain in `trackedObjects` until `destroy()`). Useful for debugging, correlating server responses against known objects, or hydrating a UI selection from a persisted `trackingId`.
+
 **Sessions**
 
 ```typescript
@@ -886,6 +894,8 @@ tracker.onCommit(response.ids);
 
 Marks a property as the server-assigned autoincrement primary key for this model. Only one `@AutoId` field is allowed per class. Enables the `onCommit` lifecycle for real-ID assignment.
 
+`@AutoId` is a **specialisation of `@Id`**: it also registers the property as part of the model's identity (so `getIdentity(obj)` includes it), but it additionally singles the property out as the one trakr will overwrite from `onCommit(keys)`. Use `@Id` for identity properties you assign yourself; use `@AutoId` for the single property trakr should patch on commit. See [`@Id`](#id) for identity-only properties (composite keys, caller-assigned UUIDs, natural keys).
+
 ```typescript
 class InvoiceModel extends TrackedObject {
   @AutoId
@@ -927,6 +937,45 @@ tracker.onCommit(serverIds);
 
 `trackingId` values are globally unique across the lifetime of the tracker and never reused, so they can safely serve as correlation keys across multiple save cycles.
 
+**Reactivity gate.** The `@AutoId` write performed by `onCommit(keys)` is a **library-internal write, not a user edit**. It does **not** fire `TrackedObject.changed` for the `@AutoId` property, does **not** bump `dirtyCounter`, does **not** re-run `@Tracked` validators, and does **not** flicker `tracker.isDirty` back to `true` during commit. After `onCommit` returns, `state === Unchanged` and `isDirty === false` — as if the object were freshly loaded with the real PK. Treat the write as *authoritative baseline update*, not as a change event.
+
+---
+
+### `@Id`
+
+Marks a property as part of the model's **caller-provided identity**. Any type is allowed (string, number, UUID, ULID, tuple-like composite via multiple decorators). Trakr never mutates the value — you set it (typically from the server, or client-generated for UUID schemas), and trakr uses it purely to compute `getIdentity(obj)`, `getIdentityObject(obj)`, and `getIdentityProperties(proto)`.
+
+```typescript
+class TenantModel extends TrackedObject {
+  @Id
+  code: string = '';        // caller-assigned string PK
+
+  @Tracked()
+  accessor name: string = '';
+}
+
+class LineItemModel extends TrackedObject {
+  @Id
+  orderId: number = 0;      // composite key part 1
+  @Id
+  lineNo: number = 0;       // composite key part 2
+
+  @Tracked()
+  accessor qty: number = 0;
+}
+```
+
+**Relationship to `@AutoId`.**
+
+|                                  | `@Id`                             | `@AutoId`                                       |
+|----------------------------------|-----------------------------------|-------------------------------------------------|
+| Registers property as identity   | yes                               | yes (implicitly)                                |
+| Value type                       | any                               | any (via `IdAssignment<V>`; historically `number`) |
+| Written by `onCommit(keys)`      | never                             | yes, from the matching `IdAssignment.value`     |
+| Multiple per class               | yes (composite key)               | no (at most one)                                |
+
+Use `@Id` for identity you own (client-generated UUIDs, natural keys, composite keys). Use `@AutoId` for the single property whose value only the server can produce and that must be patched back into the model after `onCommit`. A class may combine them: several `@Id` properties for a composite key plus one `@AutoId` for a surrogate PK, if that matches your schema.
+
 ---
 
 ### `ITracked`
@@ -951,19 +1000,24 @@ function isReady(item: ITracked): boolean {
 
 ---
 
-### `IdAssignment`
+### `IdAssignment<V>`
 
-The shape of each entry in the `keys` array passed to `tracker.onCommit(keys)`:
+The shape of each entry in the `keys` array passed to `tracker.onCommit(keys)`. Generic in the PK value type, defaulting to `number`:
 
 ```typescript
 import type { IdAssignment } from '@katn30/trakr';
-// { trackingId: number; value: number }
+// IdAssignment<V = number> = { trackingId: number; value: V }
+
+const numericKeys: IdAssignment[]           = [{ trackingId: 1, value: 42 }];
+const uuidKeys:    IdAssignment<string>[]   = [{ trackingId: 1, value: '01HXYZ-ULID' }];
 ```
 
 | Field | Type | Description |
 |---|---|---|
 | `trackingId` | `number` | The `trackingId` of the object that received a new server-assigned PK |
-| `value` | `number` | The real server-assigned ID to write to the `@AutoId` field |
+| `value` | `V` (default `number`) | The real server-assigned ID to write to the `@AutoId` field |
+
+`tracker.onCommit<V>(keys)` is generic in `V`: pass `IdAssignment<string>[]` for UUID/ULID schemas, `IdAssignment[]` for the numeric default. Trakr writes `entry.value` straight into the `@AutoId` field — the field's declared type is what enforces the match at the call site (e.g. `@AutoId id: string = ''` with `onCommit<string>(...)`).
 
 The server returns one `IdAssignment` per item that produced a new database row — both inserted objects and, in temporal tables, updated objects (see [Temporally versioned tables](#temporally-versioned-tables)). `onCommit()` iterates every entry, matches by `trackingId` against every tracked object, and writes `value` to the `@AutoId` field of any match.
 
@@ -1579,6 +1633,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.