@katn30/trakr 1.1.1 → 2.1.0

package/README.md

@@ -263,51 +263,73 @@ tracker.undo(); // reverts all four at once → status = ''
 
 Properties without `coalesceWithin` — and all `Date`, `boolean`, and `object` properties — are never coalesced; every write produces its own undo step.
 
-### Manual composing
+### Sessions
 
-When you need to group any set of writes — across multiple properties, objects, or collections — into a single undo step, use the manual composing API:
+`startSession()` returns a `TrackerSession` that groups all writes made during the session into a single undo step. Call `session.end()` to commit or `session.rollback()` to revert:
 
 ```typescript
-tracker.startComposing();
+const session = tracker.startSession();
 
 model.firstName = 'Alice';
 model.lastName  = 'Smith';
 model.email     = 'alice@example.com';
 
-tracker.endComposing(); // all three writes become one undo step
+session.end(); // all three writes become one undo step
 
 tracker.undo(); // reverts firstName, lastName, and email together
 ```
 
-Call `rollbackComposing()` instead of `endComposing()` to revert all changes made since `startComposing()`:
-
 ```typescript
-tracker.startComposing();
+const session = tracker.startSession();
 
 model.firstName = 'Alice';
 model.lastName  = 'Smith';
 
-tracker.rollbackComposing(); // all writes since startComposing are reverted
+session.rollback(); // all writes since startSession are reverted
 ```
 
-A second call to `startComposing()` while a session is already active is a no-op — nesting is not supported.
+A second call to `startSession()` while a session is already active is a no-op — nesting is not supported.
 
-**Typical use case — edit modal**
+**Edit modal with save button**
 
-Open a modal that edits a slice of the model. If the user confirms, the entire set of edits lands in the undo history as one step. If the user cancels, all edits are rolled back invisibly.
+The canonical use case is a modal that edits a slice of the model. Pass a **property scope** — a list of `[object, propertyNames]` tuples — and the session exposes `isDirty` and `isValid` bounded to those properties, so a save button can be driven correctly regardless of the state of the rest of the application.
 
 ```typescript
+import { PropertyScope } from 'trakr';
+
 function openEditModal(model: PersonModel) {
-  tracker.startComposing();
+  const session = tracker.startSession([
+    [model, ['firstName', 'lastName', 'email']],
+  ]);
 
   showModal({
     model,
-    onConfirm: () => tracker.endComposing(),
-    onCancel:  () => tracker.rollbackComposing(),
+    onConfirm: () => session.end(),
+    onCancel:  () => session.rollback(),
+    canSave:   () => session.canCommit,
   });
 }
 ```
 
+**`isDirty`** is `false` when the session starts (even if other objects are already dirty elsewhere), and becomes `true` the moment the user writes to any property listed in the scope. Defaults to `false` when no scope is provided.
+
+**`isValid`** checks `validationMessages` for every declared property. If any has a validation error — including one that existed *before* the session started — `isValid` is `false`, keeping the save button disabled until the user resolves it. Defaults to `true` when no scope is provided.
+
+**`canCommit`** is `true` when `isDirty && isValid` — ready to enable a save button.
+
+**Multiple objects in scope**
+
+Pass one tuple per object:
+
+```typescript
+const session = tracker.startSession([
+  [person,  ['firstName', 'email']],
+  [address, ['street', 'city']],
+]);
+```
+
+Properties not listed — and all other tracked objects — are ignored by `isDirty` and `isValid`. The scope has no effect on what gets committed or rolled back: `session.end()` always merges everything written since `startSession()` into one undo step, and `session.rollback()` always reverts it all.
+
 ### Dependency tracking
 
 Validators can read other properties of the same model — for example, a `scheduleDays` field might be required only when `isEnabled` is `true`. trakr automatically tracks which properties each validator reads, and re-runs only the affected validators when those properties change.
@@ -588,12 +610,19 @@ 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).
 
-**Manual composing**
+**Sessions**
 
 ```typescript
-tracker.startComposing();    // begin grouping subsequent changes
-tracker.endComposing();      // commit — all changes become one undo step
-tracker.rollbackComposing(); // revert — all changes since startComposing are rolled back
+const session = tracker.startSession();    // begin a session
+const session = tracker.startSession([…]); // same, with a property scope
+session.end();                             // commit — all changes become one undo step
+session.rollback();                        // revert — all changes since startSession
+
+session.isDirty;        // false until a scoped property is written
+session.isValid;        // false if any scoped property has a validation error
+session.canCommit;      // isDirty && isValid
+session.trackedObjects; // objects in scope ([] when no scope)
+session.deletedObjects; // scoped objects in Deleted state
 ```
 
 **Object construction**

package/dist/dev/index.cjs

@@ -27,6 +27,7 @@ __export(index_exports, {
   TrackedCollectionChanged: () => TrackedCollectionChanged,
   TrackedObject: () => TrackedObject,
   Tracker: () => Tracker,
+  TrackerSession: () => TrackerSession,
   TypedEvent: () => TypedEvent
 });
 module.exports = __toCommonJS(index_exports);
@@ -249,6 +250,242 @@ function validateSingleProperty(tracked, property) {
   return error;
 }
 
+// src/OperationProperties.ts
+var OperationProperties = class {
+  constructor(trackedObject, property, type, validator, coalesceWithin) {
+    this.trackedObject = trackedObject;
+    this.property = property;
+    this.type = type;
+    this.validator = validator;
+    this.coalesceWithin = coalesceWithin;
+  }
+};
+
+// src/ExternallyAssigned.ts
+var AUTO_ID = /* @__PURE__ */ Symbol("autoId");
+function AutoId(_target, context) {
+  context.addInitializer(function() {
+    Object.defineProperty(Object.getPrototypeOf(this), AUTO_ID, {
+      value: String(context.name),
+      configurable: true
+    });
+  });
+}
+function getAutoIdProperty(proto) {
+  return AUTO_ID in proto ? proto[AUTO_ID] : void 0;
+}
+
+// src/TrackedObjectStateMachine.ts
+function applyStateTransition(obj, event, direction, context) {
+  if (event === "added") {
+    applyAdded(obj, direction);
+  } else if (event === "removed") {
+    applyRemoved(obj, direction, context);
+  } else {
+    applyCommitted(obj, direction, context);
+  }
+}
+function applyAdded(obj, direction) {
+  if (direction === "undo") {
+    obj._setState("Unchanged" /* Unchanged */);
+  } else {
+    obj._setState("Insert" /* Insert */);
+  }
+}
+function applyRemoved(obj, direction, context) {
+  if (direction === "undo") {
+    const prev = context?.prevState ?? "Unchanged" /* Unchanged */;
+    obj._setState(prev);
+    if (prev === "Insert" /* Insert */) {
+      if (context?.prevDirtyCounter !== void 0) {
+        obj._setDirtyCounter(context.prevDirtyCounter);
+      }
+    }
+  } else {
+    if (obj.state === "Insert" /* Insert */) {
+      obj._setState("Unchanged" /* Unchanged */);
+      obj._setDirtyCounter(0);
+    } else {
+      obj._setState("Deleted" /* Deleted */);
+    }
+  }
+}
+function applyCommitted(obj, direction, context) {
+  if (direction === "undo") {
+    const prev = context?.prevState ?? "Unchanged" /* Unchanged */;
+    if (prev === "Insert" /* Insert */) {
+      obj._setState("Deleted" /* Deleted */);
+    } else if (prev === "Deleted" /* Deleted */) {
+      obj._setState("Insert" /* Insert */);
+    } else if (prev === "Changed" /* Changed */) {
+      obj._setState("Changed" /* Changed */);
+    }
+  } else {
+    if ((context?.prevState === "Insert" /* Insert */ || context?.prevState === "Changed" /* Changed */) && context.autoIdProp && context.realId !== void 0) {
+      obj[context.autoIdProp] = context.realId;
+    }
+    obj._setState("Unchanged" /* Unchanged */);
+    obj._setDirtyCounter(0);
+  }
+}
+function buildCommittedContext(obj, autoIdProp, keys) {
+  const prevState = obj.state;
+  let realId;
+  if ((prevState === "Insert" /* Insert */ || prevState === "Changed" /* Changed */) && keys) {
+    realId = keys.find((k) => k.trackingId === obj.trackingId)?.value;
+  }
+  return { prevState, autoIdProp, realId };
+}
+
+// src/TrackedObject.ts
+var TrackedObject = class {
+  constructor(tracker) {
+    this.tracker = tracker;
+    this._dirtyCounter = 0;
+    this._isValid = true;
+    this._state = "Unchanged" /* Unchanged */;
+    this.changed = new TypedEvent();
+    this.trackedChanged = new TypedEvent();
+    if (!tracker._isConstructing) {
+      throw new Error(`${this.constructor.name} must be created inside tracker.construct()`);
+    }
+    this.trackingId = tracker._nextTrackingId();
+    this.validationMessages = /* @__PURE__ */ new Map();
+    tracker._trackObject(this);
+  }
+  // ---- StateTarget interface (internal) ----
+  /** @internal */
+  get state() {
+    return this._state;
+  }
+  /** @internal */
+  _setState(value) {
+    this._state = value;
+  }
+  /** @internal */
+  _getDirtyCounter() {
+    return this._dirtyCounter;
+  }
+  /** @internal */
+  _setDirtyCounter(value) {
+    this._dirtyCounter = value;
+  }
+  // ---- Public API ----
+  get validationMessages() {
+    return this._validationMessages ?? /* @__PURE__ */ new Map();
+  }
+  set validationMessages(value) {
+    this._validationMessages = value;
+  }
+  get isValid() {
+    return this._isValid;
+  }
+  set isValid(value) {
+    const wasValid = this._isValid;
+    this._isValid = value;
+    if (wasValid !== value) {
+      this.tracker._onValidityChanged(wasValid, value);
+    }
+  }
+  get isDirty() {
+    return this._dirtyCounter !== 0;
+  }
+  get dirtyCounter() {
+    return this._dirtyCounter;
+  }
+  set dirtyCounter(value) {
+    this._dirtyCounter = value;
+  }
+  /** @internal */
+  _onCommitted(lastOp, keys) {
+    const autoIdProp = getAutoIdProperty(Object.getPrototypeOf(this));
+    const context = buildCommittedContext(this, autoIdProp, keys);
+    const redoFn = () => applyStateTransition(this, "committed", "do", context);
+    const undoFn = () => applyStateTransition(this, "committed", "undo", context);
+    if (lastOp) {
+      lastOp.updateOrAdd(redoFn, undoFn, new OperationProperties(this, "__state__", 4 /* Object */));
+    }
+    redoFn();
+  }
+  /** @internal */
+  _markRemoved() {
+    const prevState = this._state;
+    const prevDirtyCounter = this._dirtyCounter;
+    this.tracker._doAndTrack(
+      () => applyStateTransition(this, "removed", "do"),
+      () => applyStateTransition(this, "removed", "undo", { prevState, prevDirtyCounter }),
+      new OperationProperties(this, "__state__", 4 /* Object */)
+    );
+  }
+  /** @internal */
+  _markAdded() {
+    if (this._state !== "Unchanged" /* Unchanged */) return;
+    if (this.tracker._isTrackingSuppressed) return;
+    this.tracker._doAndTrack(
+      () => applyStateTransition(this, "added", "do"),
+      () => applyStateTransition(this, "added", "undo"),
+      new OperationProperties(this, "__state__", 4 /* Object */)
+    );
+  }
+  /** @internal */
+  _validate(property, errorMessage) {
+    if (errorMessage) {
+      this.validationMessages.set(property, errorMessage);
+    } else {
+      this.validationMessages.delete(property);
+    }
+    this.validationMessages = new Map(this.validationMessages);
+    this.isValid = this.validationMessages.size === 0;
+  }
+  /** @internal */
+  _applyValidation(messages) {
+    this.validationMessages = messages;
+    this.isValid = messages.size === 0;
+  }
+  destroy() {
+    DependencyTracker.clearDeps(this);
+    this.tracker._untrackObject(this);
+  }
+};
+
+// src/TrackerSession.ts
+var TrackerSession = class {
+  constructor(scope, _end, _rollback) {
+    this._end = _end;
+    this._rollback = _rollback;
+    this._isDirty = false;
+    if (scope && scope.length > 0) {
+      this._scope = new Map(scope.map(([obj, props]) => [obj, new Set(props)]));
+    }
+  }
+  /** @internal */
+  _onWrite(obj, property) {
+    if (this._scope === void 0) return;
+    const declaredProps = this._scope.get(obj);
+    if (declaredProps === void 0 || !declaredProps.has(property)) return;
+    this._isDirty = true;
+  }
+  get isDirty() {
+    if (this._scope === void 0) return void 0;
+    return this._isDirty;
+  }
+  get isValid() {
+    if (this._scope === void 0) return void 0;
+    for (const [obj, props] of this._scope) {
+      for (const prop of props) {
+        if (obj.validationMessages.has(prop)) return false;
+      }
+    }
+    return true;
+  }
+  end() {
+    this._end();
+  }
+  rollback() {
+    this._rollback();
+  }
+};
+
 // src/Tracker.ts
 var Tracker = class {
   constructor() {
@@ -422,6 +659,9 @@ var Tracker = class {
       properties
     );
     redoAction();
+    if (this._currentSession !== void 0 && properties.property !== void 0 && properties.trackedObject instanceof TrackedObject) {
+      this._currentSession._onWrite(properties.trackedObject, properties.property);
+    }
     if (this.isEndingCurrentOperation(properties)) {
       this._currentOperation = void 0;
       this._currentOperationOwner = void 0;
@@ -484,13 +724,20 @@ var Tracker = class {
     this.canRedo = this._redoOperations.length > 0;
     this.isDirty = CollectionUtilities.getLast(this._undoOperations) !== this._commitStateOperation;
   }
-  startComposing() {
-    if (this._composingBaseIndex !== void 0) return;
+  startSession(scope) {
+    if (this._currentSession !== void 0) return this._currentSession;
     this._composingBaseIndex = this._undoOperations.length;
     this._composingRedoLength = this._redoOperations.length;
+    this._currentSession = new TrackerSession(
+      scope,
+      () => this.endComposing(),
+      () => this.rollbackComposing()
+    );
+    return this._currentSession;
   }
   endComposing() {
     if (this._composingBaseIndex === void 0) return;
+    this._currentSession = void 0;
     const composed = this._undoOperations.splice(this._composingBaseIndex);
     this._redoOperations.splice(this._composingRedoLength);
     this._composingBaseIndex = void 0;
@@ -515,6 +762,7 @@ var Tracker = class {
   }
   rollbackComposing() {
     if (this._composingBaseIndex === void 0) return;
+    this._currentSession = void 0;
     const toRevert = this._undoOperations.splice(this._composingBaseIndex);
     this._redoOperations.splice(this._composingRedoLength);
     this._composingBaseIndex = void 0;
@@ -566,204 +814,6 @@ var Tracker = class {
   }
 };
 
-// src/OperationProperties.ts
-var OperationProperties = class {
-  constructor(trackedObject, property, type, validator, coalesceWithin) {
-    this.trackedObject = trackedObject;
-    this.property = property;
-    this.type = type;
-    this.validator = validator;
-    this.coalesceWithin = coalesceWithin;
-  }
-};
-
-// src/ExternallyAssigned.ts
-var AUTO_ID = /* @__PURE__ */ Symbol("autoId");
-function AutoId(_target, context) {
-  context.addInitializer(function() {
-    Object.defineProperty(Object.getPrototypeOf(this), AUTO_ID, {
-      value: String(context.name),
-      configurable: true
-    });
-  });
-}
-function getAutoIdProperty(proto) {
-  return AUTO_ID in proto ? proto[AUTO_ID] : void 0;
-}
-
-// src/TrackedObjectStateMachine.ts
-function applyStateTransition(obj, event, direction, context) {
-  if (event === "added") {
-    applyAdded(obj, direction);
-  } else if (event === "removed") {
-    applyRemoved(obj, direction, context);
-  } else {
-    applyCommitted(obj, direction, context);
-  }
-}
-function applyAdded(obj, direction) {
-  if (direction === "undo") {
-    obj._setState("Unchanged" /* Unchanged */);
-  } else {
-    obj._setState("Insert" /* Insert */);
-  }
-}
-function applyRemoved(obj, direction, context) {
-  if (direction === "undo") {
-    const prev = context?.prevState ?? "Unchanged" /* Unchanged */;
-    obj._setState(prev);
-    if (prev === "Insert" /* Insert */) {
-      if (context?.prevDirtyCounter !== void 0) {
-        obj._setDirtyCounter(context.prevDirtyCounter);
-      }
-    }
-  } else {
-    if (obj.state === "Insert" /* Insert */) {
-      obj._setState("Unchanged" /* Unchanged */);
-      obj._setDirtyCounter(0);
-    } else {
-      obj._setState("Deleted" /* Deleted */);
-    }
-  }
-}
-function applyCommitted(obj, direction, context) {
-  if (direction === "undo") {
-    const prev = context?.prevState ?? "Unchanged" /* Unchanged */;
-    if (prev === "Insert" /* Insert */) {
-      obj._setState("Deleted" /* Deleted */);
-    } else if (prev === "Deleted" /* Deleted */) {
-      obj._setState("Insert" /* Insert */);
-    } else if (prev === "Changed" /* Changed */) {
-      obj._setState("Changed" /* Changed */);
-    }
-  } else {
-    if ((context?.prevState === "Insert" /* Insert */ || context?.prevState === "Changed" /* Changed */) && context.autoIdProp && context.realId !== void 0) {
-      obj[context.autoIdProp] = context.realId;
-    }
-    obj._setState("Unchanged" /* Unchanged */);
-    obj._setDirtyCounter(0);
-  }
-}
-function buildCommittedContext(obj, autoIdProp, keys) {
-  const prevState = obj.state;
-  let realId;
-  if ((prevState === "Insert" /* Insert */ || prevState === "Changed" /* Changed */) && keys) {
-    realId = keys.find((k) => k.trackingId === obj.trackingId)?.value;
-  }
-  return { prevState, autoIdProp, realId };
-}
-
-// src/TrackedObject.ts
-var TrackedObject = class {
-  constructor(tracker) {
-    this.tracker = tracker;
-    this._dirtyCounter = 0;
-    this._isValid = true;
-    this._state = "Unchanged" /* Unchanged */;
-    this.changed = new TypedEvent();
-    this.trackedChanged = new TypedEvent();
-    if (!tracker._isConstructing) {
-      throw new Error(`${this.constructor.name} must be created inside tracker.construct()`);
-    }
-    this.trackingId = tracker._nextTrackingId();
-    this.validationMessages = /* @__PURE__ */ new Map();
-    tracker._trackObject(this);
-  }
-  // ---- StateTarget interface (internal) ----
-  /** @internal */
-  get state() {
-    return this._state;
-  }
-  /** @internal */
-  _setState(value) {
-    this._state = value;
-  }
-  /** @internal */
-  _getDirtyCounter() {
-    return this._dirtyCounter;
-  }
-  /** @internal */
-  _setDirtyCounter(value) {
-    this._dirtyCounter = value;
-  }
-  // ---- Public API ----
-  get validationMessages() {
-    return this._validationMessages ?? /* @__PURE__ */ new Map();
-  }
-  set validationMessages(value) {
-    this._validationMessages = value;
-  }
-  get isValid() {
-    return this._isValid;
-  }
-  set isValid(value) {
-    const wasValid = this._isValid;
-    this._isValid = value;
-    if (wasValid !== value) {
-      this.tracker._onValidityChanged(wasValid, value);
-    }
-  }
-  get isDirty() {
-    return this._dirtyCounter !== 0;
-  }
-  get dirtyCounter() {
-    return this._dirtyCounter;
-  }
-  set dirtyCounter(value) {
-    this._dirtyCounter = value;
-  }
-  /** @internal */
-  _onCommitted(lastOp, keys) {
-    const autoIdProp = getAutoIdProperty(Object.getPrototypeOf(this));
-    const context = buildCommittedContext(this, autoIdProp, keys);
-    const redoFn = () => applyStateTransition(this, "committed", "do", context);
-    const undoFn = () => applyStateTransition(this, "committed", "undo", context);
-    if (lastOp) {
-      lastOp.updateOrAdd(redoFn, undoFn, new OperationProperties(this, "__state__", 4 /* Object */));
-    }
-    redoFn();
-  }
-  /** @internal */
-  _markRemoved() {
-    const prevState = this._state;
-    const prevDirtyCounter = this._dirtyCounter;
-    this.tracker._doAndTrack(
-      () => applyStateTransition(this, "removed", "do"),
-      () => applyStateTransition(this, "removed", "undo", { prevState, prevDirtyCounter }),
-      new OperationProperties(this, "__state__", 4 /* Object */)
-    );
-  }
-  /** @internal */
-  _markAdded() {
-    if (this._state !== "Unchanged" /* Unchanged */) return;
-    if (this.tracker._isTrackingSuppressed) return;
-    this.tracker._doAndTrack(
-      () => applyStateTransition(this, "added", "do"),
-      () => applyStateTransition(this, "added", "undo"),
-      new OperationProperties(this, "__state__", 4 /* Object */)
-    );
-  }
-  /** @internal */
-  _validate(property, errorMessage) {
-    if (errorMessage) {
-      this.validationMessages.set(property, errorMessage);
-    } else {
-      this.validationMessages.delete(property);
-    }
-    this.validationMessages = new Map(this.validationMessages);
-    this.isValid = this.validationMessages.size === 0;
-  }
-  /** @internal */
-  _applyValidation(messages) {
-    this.validationMessages = messages;
-    this.isValid = messages.size === 0;
-  }
-  destroy() {
-    DependencyTracker.clearDeps(this);
-    this.tracker._untrackObject(this);
-  }
-};
-
 // src/Tracked.ts
 function Tracked(validator, onChange, options) {
   function decorator(target, context) {
@@ -1260,6 +1310,7 @@ var TrackedCollectionChanged = class {
   TrackedCollectionChanged,
   TrackedObject,
   Tracker,
+  TrackerSession,
   TypedEvent
 });
 //# sourceMappingURL=index.cjs.map