@katn30/trakr 4.0.0 → 4.2.0

package/README.md

@@ -463,13 +463,15 @@ Adding or removing a `TrackedObject` from a `TrackedCollection` transitions its
 ```typescript
 const item = tracker.construct(() => new ItemModel(tracker)); // Unchanged
 items.push(item);   // → Insert
-items.remove(item); // → Unchanged (was never saved)
+items.remove(item); // → Unchanged, and untracked (was never saved)
 
 const loaded = tracker.construct(() => new ItemModel(tracker, { id: 1 })); // Unchanged
 items.push(loaded);   // → Insert
 items.remove(loaded); // → Deleted
 ```
 
+Removing an item whose state is `Insert` collapses it as if it had never existed: the state resets to `Unchanged` and the object is removed from `tracker.trackedObjects` in the same undo step. You do not need to call `destroy()` yourself — the collection handles it. Undo of the remove re-tracks the item and puts it back in the collection at state `Insert`.
+
 **Via @Tracked property**
 
 When a `@Tracked` property holds a `TrackedObject` value, assigning to it has the same effect: the outgoing value transitions to `Deleted` (or `Unchanged` if it was `Insert`), and the incoming value transitions to `Insert`:
@@ -536,7 +538,7 @@ There is no separate redo transition. Redo simply re-runs the original `do` acti
 
 #### Key notes
 
-**`removed/do` from `Insert` collapses to `Unchanged`** — if an object was added and then removed before ever being committed, it was never persisted. The transition resets `dirtyCounter` to zero as if the add never happened. Nothing needs to be sent to the server.
+**`removed/do` from `Insert` collapses to `Unchanged` and untracks the object** — if an object was added and then removed before ever being committed, it was never persisted. The transition resets `dirtyCounter` to zero, removes the object from `tracker.trackedObjects`, and clears its dependency-tracking entries — as if the add never happened. Nothing needs to be sent to the server, and the object no longer contributes to `tracker.isValid`. Undo of the remove re-tracks the object and restores its previous validity accounting.
 
 **`committed/undo` reverses the server operation** — undoing past a commit puts the object into the state that requires the inverse server operation. Undoing a committed INSERT requires a DELETE; undoing a committed DELETE requires a new INSERT; undoing a committed UPDATE requires another UPDATE with the pre-edit values.
 
@@ -610,6 +612,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 +896,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 +939,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 +1002,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.
 
@@ -1136,7 +1192,7 @@ accessor status: string = '';
 
 ### `TrackedCollection<T>`
 
-A fully array-compatible tracked collection. All mutations are recorded and undoable. Implements `Array<T>` so it works anywhere an array is expected.
+A tracked collection with a full array-shaped API. All mutation methods are recorded and undoable. Implements `Array<T>` for type-level interop with array-consuming APIs — with one runtime gap, described in **Positional access at runtime** below.
 
 ```typescript
 const items = new TrackedCollection<string>(tracker);
@@ -1152,6 +1208,28 @@ const items = new TrackedCollection<string>(
 );
 ```
 
+**Positional access at runtime**
+
+`TrackedCollection<T>` declares the `[n: number]: T` index signature (inherited from `implements Array<T>`), but numeric-index access is **not** wired up at runtime. TypeScript accepts `col[n]` and `col[n] = x` without complaint, but neither behaves like a real array:
+
+- `col[0]` returns `undefined` at runtime, even when `col.length > 0`.
+- `col[0] = x` does not mutate the collection and does not trigger tracking. It silently sets a data property on the class instance that shadows the (unimplemented) indexer — subsequent `col[0]` reads will return `x` while `col.length`, iteration, and `col.collection` still reflect the real state. This divergence will not surface as an error; it will surface as inconsistent UI or a save payload missing the write.
+
+The interface is kept for interop (passing a `TrackedCollection` to code typed against `Array<T>`), but the runtime backing is deliberately not provided: wiring it up requires either a `Proxy` (breaks instance identity across the tracker API and adds an indirection layer on every property access) or per-index `defineProperty` accessors (allocates one closure per element, and numeric properties become enumerable and appear in `Object.keys` and `for...in`). Neither trade-off is worth it for a pattern the class already has first-class alternatives for.
+
+Use these instead:
+
+| Instead of | Use |
+|---|---|
+| `col[n]` (read) | `col.at(n)` — participates in dependency tracking |
+| — | `col.collection[n]` — direct read of the underlying array, no dependency tracking |
+| `col[n] = x` (write) | `col.replaceAt(n, x)` — tracked, undoable |
+| — | `col.splice(n, 1, x)` — tracked, undoable |
+| `for (let i = 0; i < col.length; i++) col[i]` | `for (const item of col) ...` |
+| — | `col.forEach(...)`, `col.map(...)`, etc. |
+
+When passing a `TrackedCollection` to a third-party function typed against `Array<T>` that reads by index internally, pass `col.collection` instead. It exposes the underlying `T[]` with zero copying. Treat it as read-only: any mutation applied to that reference bypasses the tracker entirely.
+
 **Tracked mutation methods**
 
 All of these create undo steps:

package/dist/dev/index.cjs

@@ -838,6 +838,9 @@ var Tracker = class {
     this._commitStateOperation = lastOp;
     this.reset();
   }
+  getByTrackingId(trackingId) {
+    return this.trackedObjects.find((o) => o.trackingId === trackingId);
+  }
   /** @internal */
   _isInUndoStack(op) {
     return this._undoOperations.includes(op);