@katn30/trakr 2.2.1 → 3.0.0

package/README.md

@@ -1361,6 +1361,230 @@ For `Deleted` items the PK never changes — the backend just closes the existin
 
 ---
 
+## Event generation (opt-in)
+
+trakr's core is a **state diff** — after edits, iterate `tracker.trackedObjects`, group by `state`, and ship a bulk payload. That model works for most backends, but consumers moving to **event-sourced DDD** need something different: on Save, produce a **list of typed events**, one per meaningful change, that the backend appends to an event stream.
+
+`EventTracker`, `@EventTracked`, and `EventTrackedCollection` provide a **fully opt-in** layer on top of the base API that turns dirty state into a typed event list on demand. Everything else stays identical — consumers using `Tracker` / `TrackedObject` / `TrackedCollection` / `@Tracked` see zero behavioural change.
+
+### API at a glance
+
+```typescript
+import {
+  EventTracker,
+  EventTracked,
+  EventTrackedCollection,
+  TrackedObject,
+  AutoId,
+  Tracker,
+  GeneratedEvent,
+} from '@katn30/trakr';
+
+enum IssueEvents {
+  SubmittedDetailsRevised = 'SubmittedDetailsRevised',
+  AnalysisRevised = 'AnalysisRevised',
+  StageTransitioned = 'StageTransitioned',
+  CommentAdded = 'CommentAdded',
+  CommentRemoved = 'CommentRemoved',
+  CommentEdited = 'CommentEdited',
+  CommentStatusChanged = 'CommentStatusChanged',
+}
+
+class CommentModel extends TrackedObject {
+  @AutoId
+  id: number = 0;
+
+  @EventTracked(IssueEvents.CommentEdited)
+  accessor text: string = '';
+
+  @EventTracked(IssueEvents.CommentStatusChanged)
+  accessor status: string = 'open';
+
+  constructor(t: Tracker) { super(t); }
+}
+
+class IssueModel extends TrackedObject {
+  @AutoId
+  id: number = 0;
+
+  @EventTracked(IssueEvents.SubmittedDetailsRevised)
+  accessor name: string = '';
+
+  @EventTracked(IssueEvents.SubmittedDetailsRevised)
+  accessor description: string = '';
+
+  @EventTracked(IssueEvents.AnalysisRevised)
+  accessor analysisSummary: string | null = null;
+
+  @EventTracked(IssueEvents.AnalysisRevised)
+  accessor rootCause: string | null = null;
+
+  // Declared LAST — see "Ordering" below.
+  @EventTracked(IssueEvents.StageTransitioned)
+  accessor stage: string = 'Submitted';
+
+  readonly comments: EventTrackedCollection<CommentModel>;
+
+  constructor(t: Tracker) {
+    super(t);
+    this.comments = new EventTrackedCollection<CommentModel>(
+      t,
+      [],
+      undefined,
+      {
+        itemAdded: IssueEvents.CommentAdded,
+        itemRemoved: IssueEvents.CommentRemoved,
+      },
+    );
+  }
+}
+
+const tracker = new EventTracker();
+const issue = tracker.construct(() => new IssueModel(tracker));
+tracker.onCommit(); // start clean (issue is loaded)
+
+// user makes some edits
+issue.name = 'Faulty widget';
+issue.stage = 'InAnalysis';
+
+// on Save:
+const events: GeneratedEvent<IssueEvents>[] = tracker.generateEvents<IssueEvents>();
+// events = [
+//   { eventType: 'SubmittedDetailsRevised', payload: { name: 'Faulty widget' }, trackingId: 1, targetId: ... },
+//   { eventType: 'StageTransitioned',       payload: { stage: 'InAnalysis' },    trackingId: 1, targetId: ... },
+// ]
+await api.publishEvents(events);
+tracker.onCommit();
+```
+
+`generateEvents()` is a **pure read** — no mutation, no state transitions. Calling it twice with no intervening writes returns the same list.
+
+### `@EventTracked`
+
+Drop-in replacement for `@Tracked` that adds an **event-type tag** as the first argument. Everything else — validator, `onChange`, `coalesceWithin`, undo/redo, dependency tracking, no-op detection — is identical.
+
+```typescript
+@EventTracked(eventType, validator?, onChange?, options?)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `eventType` | `string` (typically an enum value) | The tag this field contributes to |
+| `validator` | `(self, newValue) => string \| undefined` | Same as `@Tracked` |
+| `onChange` | `(self, newValue, oldValue) => void` | Same as `@Tracked` |
+| `options.coalesceWithin` | `number` | Same as `@Tracked` |
+
+**Field-cluster grouping.** All fields on a class that share the same tag collapse into **one event**, whose payload contains **only the fields that are currently dirty relative to the last committed state**. Untouched fields are never included. `@Tracked` (untagged) fields continue to work — they participate in undo/redo/validation but do not contribute to event generation.
+
+**Do not name an `@EventTracked` field `state`** — it collides with `TrackedObject.state`, which is the enum used by the state machine. Use a different name (`stage`, `status`, `phase`, `workflowState`…).
+
+### `EventTracker`
+
+Extends `Tracker` with one method:
+
+```typescript
+generateEvents<TEventType extends string = string>(): GeneratedEvent<TEventType>[]
+```
+
+Everything else is unchanged. An `EventTracker` used as a plain `Tracker` (never calling `generateEvents`) behaves **exactly** like a v2 `Tracker`. The one internal difference: `EventTracker.onCommit(keys)` also clears per-instance event-diff state, which is what makes "after commit, `generateEvents` returns `[]`" work.
+
+### `EventTrackedCollection<T>`
+
+Extends `TrackedCollection<T>` with an optional **lifecycle mapping** for item add/remove:
+
+```typescript
+new EventTrackedCollection<CommentModel>(
+  tracker,
+  initialItems,
+  validator,
+  {
+    itemAdded: IssueEvents.CommentAdded,
+    itemRemoved: IssueEvents.CommentRemoved,
+  },
+);
+```
+
+For items that are themselves `TrackedObject`s, the following per-item rules apply at generation time:
+
+| Item state | With `itemAdded` set | With `itemAdded` omitted |
+|---|---|---|
+| `Insert` | One `itemAdded` event, payload = **all** `@EventTracked` fields on the item (regardless of tag) | No event |
+| `Deleted` | One `itemRemoved` event, payload = `{}`, `targetId` = the item's `@AutoId` value | No event |
+| `Changed` | Per-field-cluster events (as if the item were a standalone `Changed` model) | Same — per-field-cluster events |
+| `Unchanged` | No event | No event |
+
+Consumers can opt in to some lifecycle events but not others — the two options are independent. If both are omitted, `EventTrackedCollection` behaves like a plain `TrackedCollection` from the events perspective: only per-field events on `Changed` items are emitted.
+
+**Insert-then-remove collapses to zero events.** If a `TrackedObject` is pushed to a collection and then removed before Save, its state returns to `Unchanged` (see [Object state machine](#object-state-machine) — `removed/do` from `Insert` collapses to `Unchanged`). No `itemAdded` event is emitted for an object that was never really added.
+
+**Collections of primitives** — `EventTrackedCollection<string>`, `EventTrackedCollection<number>`, etc. — accept the lifecycle option bag but do not currently emit lifecycle events, because primitives have no `trackingId` or per-field tags. Track primitive add/remove via `collection.changed` if you need those events.
+
+### `GeneratedEvent`
+
+```typescript
+interface GeneratedEvent<
+  TEventType extends string = string,
+  TPayload = Record<string, unknown>,
+> {
+  eventType: TEventType;
+  payload: TPayload;
+  trackingId?: number;
+  targetId?: number;
+}
+```
+
+| Field | When present | Notes |
+|---|---|---|
+| `eventType` | Always | The tag value from the consumer's enum / string-literal union |
+| `payload` | Always | For lifecycle `itemAdded`: all `@EventTracked` fields' current values. For field-cluster events: only the dirty fields carrying that tag. For lifecycle `itemRemoved`: `{}`. Values of `undefined` are normalised to `null` |
+| `trackingId` | On events emitted from `Insert` or `Changed` items | Correlate with the backend's `IdAssignment[]` response — same mechanism as v2 |
+| `targetId` | On events emitted from `Changed` or `Deleted` items when the model has `@AutoId` | The current `@AutoId` value; the backend uses it to identify the row |
+
+### Semantic rules
+
+1. **Only actual differences produce events.** trakr subscribes to `TrackedObject.changed` and maintains a per-property "original vs. current" diff since the last commit. A write, followed by another write back to the original value (or a `tracker.undo()`), removes the entry — no event is emitted for that field.
+
+2. **Insert emits everything, Changed emits deltas.** For `Insert` items, `itemAdded` sends the full snapshot of `@EventTracked` fields (a new aggregate is "born" with all its state). For `Changed` items, field-cluster events send only fields that actually changed.
+
+3. **`onCommit` resets the baseline.** After `tracker.onCommit()`, every property's "original" is its now-committed value. Subsequent edits are diffed against this new baseline. Undoing past a commit re-populates the diff naturally, because the property undo closures emit `changed` with the reversed old/new values.
+
+4. **`@Tracked` and `@EventTracked` are freely mixable on the same class.** `@Tracked` fields participate in undo/redo/validation as usual; they simply never appear in event payloads.
+
+### Ordering
+
+Event ordering is **deterministic**:
+
+1. **Object order** — objects appear in the events in the order they were registered with the tracker (typically the order they were pushed into their collections).
+2. **Field-cluster event order within one object** — determined by which of that object's `@EventTracked` fields with the same tag was **first declared** in the class body.
+
+Consumers who need semantic ordering — for example, "field revisions before a state transition, so the backend's transition precondition sees the freshly-set field values" — control it by **declaring the transition field last** in the class body. trakr does not need to know which events are "transitions"; declaration order is the entire mechanism.
+
+```typescript
+class IssueModel extends TrackedObject {
+  @EventTracked(IssueEvents.SubmittedDetailsRevised) accessor name: string = '';
+  @EventTracked(IssueEvents.AnalysisRevised)         accessor analysisSummary: string | null = null;
+  // Declared LAST → its event comes after all others.
+  @EventTracked(IssueEvents.StageTransitioned)       accessor stage: string = 'Submitted';
+}
+```
+
+Given `issue.stage = 'InAnalysis'` and `issue.analysisSummary = 'AS'`, `generateEvents()` returns:
+
+```
+[
+  { eventType: 'AnalysisRevised',    payload: { analysisSummary: 'AS' }, ... },
+  { eventType: 'StageTransitioned',  payload: { stage: 'InAnalysis' },   ... },
+]
+```
+
+Subclass `@EventTracked` fields appear **after** base-class fields, matching the declaration order across the prototype chain.
+
+### 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.
+
+---
+
 ## License
 
 MIT — Nazario Mazzotti

package/dist/dev/index.cjs

@@ -21,6 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AutoId: () => AutoId,
+  EventTracked: () => EventTracked,
+  EventTrackedCollection: () => EventTrackedCollection,
+  EventTracker: () => EventTracker,
   State: () => State,
   Tracked: () => Tracked,
   TrackedCollection: () => TrackedCollection,
@@ -1362,9 +1365,230 @@ var TrackedCollectionChanged = class {
     this.newCollection = newCollection;
   }
 };
+
+// src/EventRegistry.ts
+var EVENT_METADATA = /* @__PURE__ */ Symbol("eventMetadata");
+var instanceState = /* @__PURE__ */ new WeakMap();
+var subscribedInstances = /* @__PURE__ */ new WeakSet();
+var itemOriginCollection = /* @__PURE__ */ new WeakMap();
+function hasOwnEventMetadata(proto) {
+  return Object.prototype.hasOwnProperty.call(proto, EVENT_METADATA);
+}
+function ownEventMetadata(proto) {
+  return hasOwnEventMetadata(proto) ? proto[EVENT_METADATA] : void 0;
+}
+function registerEventProperty(proto, property, eventType) {
+  if (!hasOwnEventMetadata(proto)) {
+    Object.defineProperty(proto, EVENT_METADATA, {
+      value: /* @__PURE__ */ new Map(),
+      configurable: true
+    });
+  }
+  const map = proto[EVENT_METADATA];
+  if (!map.has(property)) {
+    map.set(property, eventType);
+  }
+}
+function getEventMetadata(proto) {
+  const chain = [];
+  let current = proto;
+  while (current) {
+    chain.push(current);
+    current = Object.getPrototypeOf(current);
+  }
+  const merged = /* @__PURE__ */ new Map();
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const own = ownEventMetadata(chain[i]);
+    if (!own) continue;
+    own.forEach((eventType, property) => {
+      if (!merged.has(property)) merged.set(property, eventType);
+    });
+  }
+  return merged;
+}
+function ensureEventStateSubscription(target) {
+  if (subscribedInstances.has(target)) return;
+  subscribedInstances.add(target);
+  target.changed.subscribe((evt) => {
+    const meta = getEventMetadata(Object.getPrototypeOf(target));
+    if (!meta.has(evt.property)) return;
+    const state = getOrCreateEventState(target);
+    let entry = state.get(evt.property);
+    if (!entry) {
+      entry = { originalValue: evt.oldValue, currentValue: evt.newValue };
+      state.set(evt.property, entry);
+    } else {
+      entry.currentValue = evt.newValue;
+    }
+    if (entry.currentValue === entry.originalValue) {
+      state.delete(evt.property);
+    }
+  });
+}
+function getOrCreateEventState(target) {
+  let state = instanceState.get(target);
+  if (!state) {
+    state = /* @__PURE__ */ new Map();
+    instanceState.set(target, state);
+  }
+  return state;
+}
+function getEventState(target) {
+  return instanceState.get(target) ?? /* @__PURE__ */ new Map();
+}
+function clearEventState(target) {
+  instanceState.delete(target);
+}
+function recordItemOrigin(item, collection) {
+  itemOriginCollection.set(item, collection);
+}
+function getItemOrigin(item) {
+  return itemOriginCollection.get(item);
+}
+
+// src/EventTracker.ts
+var EventTracker = class extends Tracker {
+  onCommit(keys) {
+    super.onCommit(keys);
+    for (const obj of this.trackedObjects) {
+      clearEventState(obj);
+    }
+  }
+  generateEvents() {
+    const events = [];
+    for (const obj of this.trackedObjects) {
+      const meta = getEventMetadata(Object.getPrototypeOf(obj));
+      const origin = getItemOrigin(obj);
+      const lifecycle = origin?._lifecycleOptions;
+      switch (obj.state) {
+        case "Insert" /* Insert */:
+          if (lifecycle?.itemAdded) {
+            events.push(buildItemAddedEvent(obj, meta, lifecycle.itemAdded));
+          }
+          break;
+        case "Deleted" /* Deleted */:
+          if (lifecycle?.itemRemoved) {
+            events.push(buildItemRemovedEvent(obj, lifecycle.itemRemoved));
+          }
+          break;
+        case "Changed" /* Changed */:
+          pushFieldClusterEvents(obj, meta, events);
+          break;
+        case "Unchanged" /* Unchanged */:
+        default:
+          break;
+      }
+    }
+    return events;
+  }
+};
+function buildItemAddedEvent(obj, meta, eventType) {
+  const payload = {};
+  for (const [propertyName] of meta) {
+    const value = obj[propertyName];
+    payload[propertyName] = normalizeValue(value);
+  }
+  return {
+    eventType,
+    payload,
+    trackingId: obj.trackingId
+  };
+}
+function buildItemRemovedEvent(obj, eventType) {
+  const autoIdProp = getAutoIdProperty(Object.getPrototypeOf(obj));
+  const targetId = autoIdProp ? obj[autoIdProp] : void 0;
+  const event = {
+    eventType,
+    payload: {}
+  };
+  if (typeof targetId === "number") {
+    event.targetId = targetId;
+  }
+  return event;
+}
+function pushFieldClusterEvents(obj, meta, events) {
+  const state = getEventState(obj);
+  if (state.size === 0) return;
+  const grouped = /* @__PURE__ */ new Map();
+  for (const [propertyName, eventType] of meta) {
+    if (!state.has(propertyName)) continue;
+    let bucket = grouped.get(eventType);
+    if (!bucket) {
+      bucket = [];
+      grouped.set(eventType, bucket);
+    }
+    bucket.push(propertyName);
+  }
+  const autoIdProp = getAutoIdProperty(Object.getPrototypeOf(obj));
+  const targetIdRaw = autoIdProp ? obj[autoIdProp] : void 0;
+  for (const [eventType, propertyNames] of grouped) {
+    const payload = {};
+    for (const propertyName of propertyNames) {
+      payload[propertyName] = normalizeValue(state.get(propertyName).currentValue);
+    }
+    const event = {
+      eventType,
+      payload,
+      trackingId: obj.trackingId
+    };
+    if (typeof targetIdRaw === "number") {
+      event.targetId = targetIdRaw;
+    }
+    events.push(event);
+  }
+}
+function normalizeValue(value) {
+  return value === void 0 ? null : value;
+}
+
+// src/EventTracked.ts
+function EventTracked(eventType, validator, onChange, options) {
+  const trackedDecorator = Tracked(validator, onChange, options);
+  function decorator(target, context) {
+    const result = trackedDecorator(target, context);
+    const propertyName = String(context.name);
+    context.addInitializer(function() {
+      registerEventProperty(
+        Object.getPrototypeOf(this),
+        propertyName,
+        eventType
+      );
+      ensureEventStateSubscription(this);
+    });
+    return result;
+  }
+  return decorator;
+}
+
+// src/EventTrackedCollection.ts
+var EventTrackedCollection = class extends TrackedCollection {
+  constructor(tracker, items, validator, eventOptions) {
+    super(tracker, items, validator);
+    this._eventOptions = eventOptions;
+    for (const item of this.collection) {
+      if (item instanceof TrackedObject) {
+        recordItemOrigin(item, this);
+      }
+    }
+    this.changed.subscribe((evt) => {
+      for (const item of evt.added) {
+        if (item instanceof TrackedObject) {
+          recordItemOrigin(item, this);
+        }
+      }
+    });
+  }
+  /** @internal */
+  get _lifecycleOptions() {
+    return this._eventOptions;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AutoId,
+  EventTracked,
+  EventTrackedCollection,
+  EventTracker,
   State,
   Tracked,
   TrackedCollection,