ItemChange and ChangeEvent

The vocabulary noggin.onDidChange fires with. ItemChange is one observable shift (added / removed / moved / updated / activeChanged); ChangeEvent is a flat list of them, describing every difference between the previous and current snapshot. Same shape whether the mutation originated in-process or from the provider observing an outside write.

ItemChange

type ItemChange = 
  | {
  key: ItemKey;
  kind: "added";
  parentKey: ItemKey | null;
  position: number;
}
  | {
  key: ItemKey;
  kind: "removed";
}
  | {
  from: {
     parentKey: ItemKey | null;
     position: number;
  };
  key: ItemKey;
  kind: "moved";
  to: {
     parentKey: ItemKey | null;
     position: number;
  };
}
  | {
  fields: ("title" | "done" | "notes")[];
  key: ItemKey;
  kind: "updated";
}
  | {
  from: ItemKey | null;
  kind: "activeChanged";
  to: ItemKey | null;
};

One observable change to a Noggin. The vocabulary is deliberately small and decoupled from AtomicOp: listeners observe what changed, not which op caused it.

position is the 0-based index among siblings of parentKey. For moved, from describes the position in the document before the change and to after.

ChangeEvent

type ChangeEvent = readonly ItemChange[];

Payload of Noggin.onDidChange. A flat list of every shift between the previous document state and the current one.

The shape is provider-agnostic: every provider fires ChangeEvent (an ItemChange[]) for both in-process mutations and externally- observed reloads. Listeners receive the same value regardless of which side caused the change.