trakked 1.2.0 → 2.2.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:
@@ -400,7 +428,7 @@ const invoice = tracker.construct(() => new InvoiceModel(tracker));
 | `state` | `ObjectState` | Computed DB operation required at save time |
 | `_committedState` | `ObjectState` | The persisted state. Defaults to `Unchanged`. Pass `initialState` to the constructor to override |
 | `destroy()` | `void` | Removes this model from the tracker |
-| `onCommitted()` | `void` | Called automatically by `tracker.onCommit()` — resets `dirtyCounter` to `0` |
+| `onCommitted()` | `void` | Called automatically by `tracker.onCommit()` — transitions `_committedState` and records the inverse in the undo stack so that undoing a commit restores the correct state |
 
 ---
 
@@ -421,6 +449,16 @@ import { ObjectState } from 'trakked';
 
 `Edited` is **derived**: when `_committedState === Unchanged` and the object has unsaved property changes (`isDirty === true`), `state` returns `Edited`. It is never stored directly.
 
+**Undo of a committed save:**
+
+`tracker.onCommit()` records the state transition in the undo stack. Undoing past a commit reverses the server operation:
+
+| Committed operation | State after undo | Required server operation |
+|---|---|---|
+| INSERT (`New`) | `Deleted` | DELETE |
+| UPDATE (`Edited`) | `Edited` (with pre-edit values) | UPDATE |
+| DELETE (`Deleted`) | `New` | INSERT |
+
 **Loading from DB:**
 
 Objects default to `Unchanged`, so no extra setup is needed. Property values set inside the constructor are suppressed by `tracker.construct()`:
@@ -467,12 +505,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()
@@ -522,7 +560,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
@@ -664,14 +702,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)
@@ -686,7 +724,7 @@ class OrderLine extends VersionedTrackedObject {
 }
 
 class OrderModel extends VersionedTrackedObject {
-  @ExternallyAssigned
+  @AutoId
   id: number = 0;
 
   @Tracked((_, v) => !v ? 'Status is required' : undefined)
@@ -776,13 +814,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()
@@ -826,7 +864,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):**
 
@@ -870,6 +908,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.
@@ -896,6 +970,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
@@ -476,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;
@@ -487,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) {
@@ -626,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;
@@ -760,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 = () => {
@@ -795,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;
@@ -847,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) {
@@ -1288,7 +1295,7 @@ var TrackedCollectionChanged = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ExternallyAssigned,
+  AutoId,
   ObjectState,
   OperationProperties,
   PropertyType,