trakked 1.1.0 → 2.1.0

package/README.md

@@ -120,6 +120,34 @@ To disable coalescing for a specific `string` or `number` property while leaving
 accessor version: number = 0; // every increment is its own undo step
 ```
 
+### Dependency tracking
+
+Validators can read other properties of the same model — for example, a `scheduleDays` field might be required only when `isEnabled` is `true`. Trakked automatically tracks which properties each validator reads, and re-runs only the affected validators when those properties change.
+
+This works via a lightweight dependency tracking mechanism built into the `@Tracked` getter. Every time a validator runs, Trakked collects every `@Tracked` property that is read during the call. These are recorded as dependencies. When any of those properties is written next, only the validators that declared a dependency on it are re-evaluated — not the entire model.
+
+**Consequence for `get`/`set` pairs:** The dependency is registered through the getter, not the setter. If a property is written via a plain setter and its getter is not decorated with `@Tracked`, any validator that reads it will not discover the dependency — and will not re-run when the property changes.
+
+```typescript
+// WRONG — isEnabled getter is plain; validators that read self.isEnabled
+// will not re-run when isEnabled changes
+get isEnabled(): boolean { return this._isEnabled; }
+
+@Tracked()
+set isEnabled(value: boolean) { this._isEnabled = value; }
+```
+
+```typescript
+// CORRECT — both getter and setter are decorated
+@Tracked()
+get isEnabled(): boolean { return this._isEnabled; }
+
+@Tracked()
+set isEnabled(value: boolean) { this._isEnabled = value; }
+```
+
+When using `accessor` fields this is never an issue — the getter and setter share the same decoration.
+
 ### Construction via tracker.construct()
 
 All tracked model objects must be created inside `tracker.construct()`. This call:
@@ -229,6 +257,8 @@ const tracker = new Tracker(undefined);         // coalescing disabled
 | `isDirtyChanged` | `TypedEvent<boolean>` | Fires whenever `isDirty` changes |
 | `isValidChanged` | `TypedEvent<boolean>` | Fires whenever `isValid` changes |
 | `canCommitChanged` | `TypedEvent<boolean>` | Fires whenever `canCommit` changes |
+| `version` | `number` | Monotonically changing counter — starts at `0`, increments on every new operation, decrements on undo, increments on redo |
+| `versionChanged` | `TypedEvent<number>` | Fires with the new version every time `version` changes |
 | `trackedObjects` | `TrackedObjectBase[]` | All registered models |
 | `trackedCollections` | `TrackedCollection<any>[]` | All registered collections |
 
@@ -336,6 +366,38 @@ function openEditModal(model: PersonModel) {
 }
 ```
 
+**React integration — `useSyncExternalStore`**
+
+`version` and `versionChanged` are designed to plug directly into React's `useSyncExternalStore`. Subscribe to `versionChanged` as the store and snapshot `tracker.version` — any component that calls the hook will automatically re-render on every tracked mutation, undo, or redo with no bridging code required:
+
+```typescript
+import { useSyncExternalStore } from 'react';
+import { Tracker } from 'trakked';
+
+function useTrackerVersion(tracker: Tracker): number {
+  return useSyncExternalStore(
+    (onStoreChange) => tracker.versionChanged.subscribe(onStoreChange),
+    () => tracker.version,
+  );
+}
+```
+
+Any component that calls `useTrackerVersion(tracker)` will re-render whenever the tracker's state changes.
+
+```tsx
+function InvoiceForm({ tracker, invoice }: { tracker: Tracker; invoice: InvoiceModel }) {
+  useTrackerVersion(tracker); // re-renders on every mutation, undo, or redo
+
+  return (
+    <form>
+      <input value={invoice.status} onChange={(e) => { invoice.status = e.target.value; }} />
+      <button disabled={!tracker.canUndo} onClick={() => tracker.undo()}>Undo</button>
+      <button disabled={!tracker.canCommit} onClick={save}>Save</button>
+    </form>
+  );
+}
+```
+
 ---
 
 ### `TrackedObject`
@@ -433,12 +495,12 @@ Use this instead of `TrackedObject` when your database is **versioned (temporal)
 import {
   VersionedTrackedObject,
   VersionedObjectState,
-  ExternallyAssigned,
+  AutoId,
   Tracked,
 } from 'trakked';
 
 class OrderModel extends VersionedTrackedObject {
-  @ExternallyAssigned
+  @AutoId
   id: number = 0;
 
   @Tracked()
@@ -488,7 +550,7 @@ Objects default to `Unchanged`. Set properties inside the constructor — they a
 
 ```typescript
 class OrderModel extends VersionedTrackedObject {
-  @ExternallyAssigned id: number = 0;
+  @AutoId id: number = 0;
   @Tracked() accessor description: string = '';
   constructor(tracker: Tracker, data?: { id: number; description: string }) {
     super(tracker); // initialState defaults to Unchanged
@@ -630,14 +692,14 @@ import {
   VersionedTrackedObject,
   VersionedObjectState,
   Tracked,
-  ExternallyAssigned,
+  AutoId,
   TrackedCollection,
 } from 'trakked';
 
 const tracker = new Tracker();
 
 class OrderLine extends VersionedTrackedObject {
-  @ExternallyAssigned
+  @AutoId
   id: number = 0;
 
   @Tracked((_, v) => !v ? 'Description is required' : undefined)
@@ -652,7 +714,7 @@ class OrderLine extends VersionedTrackedObject {
 }
 
 class OrderModel extends VersionedTrackedObject {
-  @ExternallyAssigned
+  @AutoId
   id: number = 0;
 
   @Tracked((_, v) => !v ? 'Status is required' : undefined)
@@ -742,13 +804,13 @@ for (const obj of tracker.trackedObjects) {
 
 ---
 
-### `@ExternallyAssigned`
+### `@AutoId`
 
-Marks a numeric ID property as assigned by the server. Works with both `TrackedObject` and `VersionedTrackedObject`. Enables the `beforeCommit` / `onCommit` lifecycle for ID management.
+Marks a property as the server-assigned autoincrement primary key for this model. Works with both `TrackedObject` and `VersionedTrackedObject`. Only one `@AutoId` field is allowed per class. Enables the `beforeCommit` / `onCommit` lifecycle for placeholder ID management.
 
 ```typescript
 class InvoiceModel extends TrackedObject {
-  @ExternallyAssigned
+  @AutoId
   id: number = 0;
 
   @Tracked()
@@ -792,7 +854,7 @@ The placeholder counter never resets — each cycle continues from where it left
 
 ### `@Tracked()`
 
-The property decorator. Intercepts every write, records an undo/redo pair, and optionally validates the new value. Works with both `accessor` fields and explicit `get`/`set` pairs. Place it on the **accessor** or the **setter**.
+The property decorator. Intercepts every write, records an undo/redo pair, and optionally validates the new value. Works with `accessor` fields, explicit `get`/`set` pairs, and plain getters. Place it on the **accessor**, the **setter**, or the **getter**.
 
 **With `accessor` (recommended):**
 
@@ -836,6 +898,42 @@ class ProductModel extends TrackedObject {
 }
 ```
 
+**With `get`/`set` and side effects** — decorate both getter and setter:
+
+When the setter contains side-effect logic that must stay intact (e.g. cascading writes to other properties), decorate both the getter and the setter. The getter decoration registers `isEnabled` as a dependency source — any validator that reads it will automatically re-run when the setter fires. The setter decoration handles undo/redo as usual.
+
+```typescript
+class RuleModel extends TrackedObject {
+  private _isEnabled: boolean = false;
+
+  @Tracked()
+  get isEnabled(): boolean { return this._isEnabled; }
+
+  @Tracked()
+  set isEnabled(value: boolean) {
+    this._isEnabled = value;
+    if (value) {
+      this.scheduleDays = 'mon';
+    } else {
+      this.scheduleDays = '';
+    }
+  }
+
+  @Tracked((self: RuleModel, v) =>
+    self.isEnabled && !v ? 'Day is required' : undefined
+  )
+  accessor scheduleDays: string = '';
+
+  constructor(tracker: Tracker) {
+    super(tracker);
+  }
+}
+```
+
+When `isEnabled` is set to `true`, `scheduleDays`'s validator automatically re-runs because the getter declared the dependency. No manual `revalidate()` call is needed.
+
+> Note: decorating just the getter (without the setter) is valid when the getter is purely computed — it registers the property as a dependency source without attaching any undo/redo logic.
+
 **With a validator:**
 
 The validator receives the model instance and the incoming value. Return an error string to fail, `undefined` to pass.
@@ -862,6 +960,8 @@ class OrderModel extends TrackedObject {
 
 Validators are re-evaluated after every tracked write and after every undo/redo. Results are stored in `model.validationMessages` and rolled up into `tracker.isValid`.
 
+Validators that read other properties automatically re-run when those properties change — this is handled by the dependency tracking mechanism (see [Dependency tracking](#dependency-tracking) in Concepts). For this to work, every property read inside a validator must be exposed through a `@Tracked`-decorated getter. `accessor` fields satisfy this automatically. For `get`/`set` pairs, both the getter and setter must be decorated with `@Tracked` — see the "getter + setter with side effects" example above.
+
 **No-op detection**
 
 Assigning the same value twice does not create an undo step and does not mark the model dirty. `null` and `undefined` are treated as equivalent to `''` for string properties.

package/dist/dev/index.cjs

@@ -20,7 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  ExternallyAssigned: () => ExternallyAssigned,
+  AutoId: () => AutoId,
   ObjectState: () => ObjectState,
   OperationProperties: () => OperationProperties,
   PropertyType: () => PropertyType,
@@ -127,17 +127,17 @@ var CollectionUtilities = class {
 };
 
 // src/ExternallyAssigned.ts
-var EXTERNALLY_ASSIGNED = /* @__PURE__ */ Symbol("externallyAssigned");
-function ExternallyAssigned(_target, context) {
+var AUTO_ID = /* @__PURE__ */ Symbol("autoId");
+function AutoId(_target, context) {
   context.addInitializer(function() {
-    Object.defineProperty(Object.getPrototypeOf(this), EXTERNALLY_ASSIGNED, {
+    Object.defineProperty(Object.getPrototypeOf(this), AUTO_ID, {
       value: String(context.name),
       configurable: true
     });
   });
 }
-function getExternallyAssignedProperty(proto) {
-  return EXTERNALLY_ASSIGNED in proto ? proto[EXTERNALLY_ASSIGNED] : void 0;
+function getAutoIdProperty(proto) {
+  return AUTO_ID in proto ? proto[AUTO_ID] : void 0;
 }
 
 // src/DependencyTracker.ts
@@ -277,9 +277,11 @@ var Tracker = class {
     this._externallyAssignedPlaceholderCounter = -1;
     this._invalidCount = 0;
     this._constructionDepth = 0;
+    this._version = 0;
     this.trackedObjects = [];
     this.trackedCollections = [];
     this.isDirtyChanged = new TypedEvent();
+    this.versionChanged = new TypedEvent();
     this.isValidChanged = new TypedEvent();
     this.canCommitChanged = new TypedEvent();
     this.coalescingWindowMs = coalescingWindowMs;
@@ -306,6 +308,9 @@ var Tracker = class {
       this.updateCanCommit();
     }
   }
+  get version() {
+    return this._version;
+  }
   get isValid() {
     return this._isValid;
   }
@@ -414,6 +419,8 @@ var Tracker = class {
         this._undoOperations.push(this._currentOperation);
         this._redoOperations.length = 0;
         this.reset();
+        this._version++;
+        this.versionChanged.emit(this._version);
       }
     }
     this._currentOperation?.add(
@@ -469,7 +476,7 @@ var Tracker = class {
   onCommit(keys) {
     const lastOp = CollectionUtilities.getLast(this._undoOperations);
     if (keys) {
-      this.trackedObjects.forEach((obj) => obj.applyExternalAssignments(keys, lastOp));
+      this.trackedObjects.forEach((obj) => obj.applyServerIds(keys, lastOp));
     }
     this.trackedObjects.forEach((obj) => obj.onCommitted(lastOp));
     this._commitStateOperation = lastOp;
@@ -480,7 +487,7 @@ var Tracker = class {
   }
   beforeCommit() {
     this.trackedObjects.forEach((model) => {
-      const propertyName = getExternallyAssignedProperty(
+      const propertyName = getAutoIdProperty(
         Object.getPrototypeOf(model)
       );
       if (propertyName && model[propertyName] <= 0) {
@@ -493,6 +500,53 @@ var Tracker = class {
     this.canRedo = this._redoOperations.length > 0;
     this.isDirty = CollectionUtilities.getLast(this._undoOperations) !== this._commitStateOperation;
   }
+  startCoalescing() {
+    if (this._composingBaseIndex !== void 0) return;
+    this._composingBaseIndex = this._undoOperations.length;
+    this._composingRedoLength = this._redoOperations.length;
+  }
+  endCoalescing() {
+    if (this._composingBaseIndex === void 0) return;
+    const composed = this._undoOperations.splice(this._composingBaseIndex);
+    this._redoOperations.splice(this._composingRedoLength);
+    this._composingBaseIndex = void 0;
+    this._composingRedoLength = void 0;
+    if (composed.length === 0) {
+      this.reset();
+      return;
+    }
+    if (composed.length === 1) {
+      this._undoOperations.push(composed[0]);
+      this.reset();
+      return;
+    }
+    const merged = new Operation();
+    for (const op of composed) {
+      for (const action of op.actions) {
+        merged.add(action.redoAction, action.undoAction, action.properties);
+      }
+    }
+    this._undoOperations.push(merged);
+    this.reset();
+  }
+  rollbackCoalescing() {
+    if (this._composingBaseIndex === void 0) return;
+    const toRevert = this._undoOperations.splice(this._composingBaseIndex);
+    this._redoOperations.splice(this._composingRedoLength);
+    this._composingBaseIndex = void 0;
+    this._composingRedoLength = void 0;
+    this.withTrackingSuppressed(() => {
+      for (let i = toRevert.length - 1; i >= 0; i--) {
+        toRevert[i].undo();
+      }
+    });
+    this.reset();
+    this.revalidate();
+    if (toRevert.length > 0) {
+      this._version -= toRevert.length;
+      this.versionChanged.emit(this._version);
+    }
+  }
   undo() {
     if (!this.canUndo) {
       return;
@@ -502,6 +556,8 @@ var Tracker = class {
     this._redoOperations.push(undoOperation);
     this.reset();
     this.revalidate();
+    this._version--;
+    this.versionChanged.emit(this._version);
   }
   redo() {
     if (!this.canRedo) {
@@ -512,6 +568,8 @@ var Tracker = class {
     this._undoOperations.push(redoOperation);
     this.reset();
     this.revalidate();
+    this._version++;
+    this.versionChanged.emit(this._version);
   }
   revalidate() {
     this.trackedObjects.forEach((x) => validate(x));
@@ -568,8 +626,8 @@ var TrackedObjectBase = class {
   set dirtyCounter(value) {
     this._dirtyCounter = value;
   }
-  applyExternalAssignments(keys, lastOp) {
-    const propertyName = getExternallyAssignedProperty(Object.getPrototypeOf(this));
+  applyServerIds(keys, lastOp) {
+    const propertyName = getAutoIdProperty(Object.getPrototypeOf(this));
     if (!propertyName || this[propertyName] >= 0) return;
     const response = keys.find((x) => x.placeholder === this[propertyName]);
     if (!response) return;
@@ -702,10 +760,10 @@ var VersionedTrackedObject = class extends TrackedObjectBase {
     }
     this.dirtyCounter = 0;
   }
-  applyExternalAssignments(keys, lastOp) {
-    const propertyName = getExternallyAssignedProperty(Object.getPrototypeOf(this));
+  applyServerIds(keys, lastOp) {
+    const propertyName = getAutoIdProperty(Object.getPrototypeOf(this));
     const response = propertyName && this[propertyName] < 0 ? keys.find((x) => x.placeholder === this[propertyName]) : void 0;
-    super.applyExternalAssignments(keys, lastOp);
+    super.applyServerIds(keys, lastOp);
     if (!response) return;
     const newValue = response.value;
     const redoFn = () => {
@@ -737,7 +795,7 @@ var VersionedTrackedObject = class extends TrackedObjectBase {
     const prev = this._committedState;
     const isNeverPersisted = prev === "New" /* New */ || prev === "InsertReverted" /* InsertReverted */;
     const target = isNeverPersisted ? "Unchanged" /* Unchanged */ : "Deleted" /* Deleted */;
-    const propertyName = getExternallyAssignedProperty(Object.getPrototypeOf(this));
+    const propertyName = getAutoIdProperty(Object.getPrototypeOf(this));
     const prevId = propertyName !== void 0 ? this[propertyName] : void 0;
     const prevPendingHardDeletes = new Set(this.pendingHardDeletes);
     const prevDirtyCounter = this.dirtyCounter;
@@ -789,6 +847,13 @@ var VersionedTrackedObject = class extends TrackedObjectBase {
 function Tracked(validator, options) {
   function decorator(target, context) {
     const propertyName = String(context.name);
+    if (context.kind === "getter") {
+      const getterFn = target;
+      return function() {
+        DependencyTracker.record(this, propertyName);
+        return getterFn.call(this);
+      };
+    }
     if (context.kind === "accessor") {
       const accessorTarget = target;
       if (validator) {
@@ -1230,7 +1295,7 @@ var TrackedCollectionChanged = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ExternallyAssigned,
+  AutoId,
   ObjectState,
   OperationProperties,
   PropertyType,