Interface TransientTrait

A Transient is an object that changes over time.

It's build in such a way that we cannot observe directly its state, but we may observe and detect abstract changes that happen to it.

Definition of the word transient:

not lasting, enduring, or permanent; transitory

It is based on 3 fundamental operations:

1) Taking a snapshot of the Transient

A snapshot retains the state of the Transient at a specific moment. It returns a TransientSnapshotChanged function, which may be called to detect if a change happened in the Transient since this snapshot was taken.

It answers the question: "Did my transient changed since I took this snapshot ?"

Types

interface Transient {
 takeSnapshot: TakeTransientSnapshot;
}

interface TakeTransientSnapshot {
  (): TransientSnapshotChanged;
}

interface TransientSnapshotChanged {
  (): boolean;
}
Copy

Example

const snapshot = transient.takeSnapshot();

setInterval(() => {
 console.log('transient changed ?', snapshot());
}, 1000);
Copy

2) Listening to Transient activity

To detect changes happening inside a Transient, we could pull/call frequently the TransientSnapshotChanged function (see previous example). However, in most cases, this would be inefficient.

Instead, we may rely on the TrackTransientActivity function, which creates a listener called when activity is detected inside the Transient.

Types

interface Transient {
 onActivity: TrackTransientActivity;
}

interface TrackTransientActivity {
  (onActivity: TransientActivity): UndoFunction;
}

interface TransientActivity {
  (): void;
}
Copy

Example

const snapshot = transient.takeSnapshot();

const stopListener = transient.onActivity(() => {
  if (snapshot()) {
    console.log('transient changed !');
    stopListener();
  }
});
Copy

The activity is not necessarily triggered when the Transient changed. It simply happens when a change MAY exist.

This duality is important, and is one of the key of the reactivity of a Transient: a mix between pull (TransientSnapshotChanged) and push (TransientActivity). That permit to create lazy updates of internal state.

3) Capturing the Transient

Finally, a Transient is made to be captured into the context of a callback.

Example

const a = new Transient(...);
const b = new Transient(...);

Transient.runInContext(
 (capturedTransient: Transient) => {
  console.log('captured', capturedTransient);
  // will log `a` and `b`
 },
 () => {
   a.capture();
   b.capture();
 },
);
Copy

This mechanism is used to observe and/or derive many Transient in a simple manner.