@jay-framework/reactive 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+declare enum MeasureOfChange {
+    NO_CHANGE = 0,
+    PARTIAL = 1,
+    FULL = 2
+}
+type Next<T> = (t: T) => T;
+type Setter<T> = (t: T | Next<T>) => T;
+type Getter<T> = () => T;
+type Reaction = (measureOfChange: MeasureOfChange) => void;
+type ValueOrGetter<T> = T | Getter<T>;
+declare const GetterMark: unique symbol;
+declare const SetterMark: unique symbol;
+declare class Reactive {
+    private batchedReactionsToRun;
+    private isAutoBatchScheduled;
+    protected reactionIndex: number;
+    private reactions;
+    private reactionDependencies;
+    private dirty;
+    private dirtyResolve;
+    private timeout;
+    protected inBatchReactions: boolean;
+    private inFlush;
+    private reactionGlobalKey;
+    private reactivesToFlush;
+    private disabled;
+    private allowedPairedReactives;
+    createSignal<T>(value: ValueOrGetter<T>, measureOfChange?: MeasureOfChange): [get: Getter<T>, set: Setter<T>];
+    protected triggerReaction(index: number, measureOfChange: MeasureOfChange, paired: boolean): void;
+    enablePairing(sourceReactive: Reactive): void;
+    createReaction(func: Reaction): void;
+    batchReactions<T>(func: () => T): T;
+    private ScheduleAutoBatchRuns;
+    toBeClean(): Promise<void>;
+    private runReaction;
+    flush(): void;
+    enable(): void;
+    disable(): void;
+}
+declare function setMkReactive(mkReactive: (...reactiveNames: (string | number)[]) => Reactive): void;
+declare function mkReactive(...reactiveNames: (string | number)[]): Reactive;
+
+export { type Getter, GetterMark, MeasureOfChange, type Next, type Reaction, Reactive, type Setter, SetterMark, type ValueOrGetter, mkReactive, setMkReactive };

package/dist/index.js

@@ -0,0 +1,209 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+var MeasureOfChange = /* @__PURE__ */ ((MeasureOfChange2) => {
+  MeasureOfChange2[MeasureOfChange2["NO_CHANGE"] = 0] = "NO_CHANGE";
+  MeasureOfChange2[MeasureOfChange2["PARTIAL"] = 1] = "PARTIAL";
+  MeasureOfChange2[MeasureOfChange2["FULL"] = 2] = "FULL";
+  return MeasureOfChange2;
+})(MeasureOfChange || {});
+const GetterMark = Symbol.for("getterMark");
+const SetterMark = Symbol.for("setterMark");
+const runningReactions = [];
+function pushRunningReaction(reactiveGlobalKey) {
+  runningReactions.push(reactiveGlobalKey);
+}
+function popRunningReaction() {
+  runningReactions.pop();
+}
+class Reactive {
+  constructor() {
+    __publicField(this, "batchedReactionsToRun", []);
+    __publicField(this, "isAutoBatchScheduled", false);
+    __publicField(this, "reactionIndex", 0);
+    __publicField(this, "reactions", []);
+    __publicField(this, "reactionDependencies", []);
+    __publicField(this, "dirty", Promise.resolve());
+    __publicField(this, "dirtyResolve");
+    __publicField(this, "timeout");
+    __publicField(this, "inBatchReactions");
+    __publicField(this, "inFlush");
+    __publicField(this, "reactionGlobalKey", []);
+    __publicField(this, "reactivesToFlush", /* @__PURE__ */ new Set());
+    __publicField(this, "disabled", false);
+    __publicField(this, "allowedPairedReactives", /* @__PURE__ */ new WeakSet());
+  }
+  createSignal(value, measureOfChange = 2) {
+    let current;
+    const reactionsToRerun = [];
+    let pairedReactionsToRun = /* @__PURE__ */ new Set();
+    const triggerReactions = () => {
+      for (let index = 0; index < reactionsToRerun.length; index++) {
+        if (reactionsToRerun[index]) {
+          this.triggerReaction(index, measureOfChange, false);
+        }
+      }
+      pairedReactionsToRun.forEach(([reactive, index]) => {
+        if (reactive.allowedPairedReactives.has(this)) {
+          reactive.triggerReaction(index, measureOfChange, true);
+          this.reactivesToFlush.add(reactive);
+        }
+      });
+    };
+    const setter = (value2) => {
+      let materializedValue = typeof value2 === "function" ? value2(current) : value2;
+      let isModified = materializedValue !== current;
+      current = materializedValue;
+      if (isModified) {
+        triggerReactions();
+      }
+      return current;
+    };
+    const resetDependency = (reactionGlobalKey) => {
+      reactionsToRerun[reactionGlobalKey[1]] = false;
+    };
+    const resetPairedDependency = (reactionGlobalKey) => {
+      pairedReactionsToRun.delete(reactionGlobalKey);
+    };
+    const getter = () => {
+      const runningReactionsLength = runningReactions.length;
+      for (let index = runningReactionsLength - 1; index > -1; index--) {
+        const [reactive, reactionIndex] = runningReactions[index];
+        if (reactive === this) {
+          reactionsToRerun[reactionIndex] = true;
+          this.reactionDependencies[reactionIndex].add(resetDependency);
+          break;
+        } else {
+          pairedReactionsToRun.add(runningReactions[index]);
+          reactive.reactionDependencies[reactionIndex].add(resetPairedDependency);
+        }
+      }
+      return current;
+    };
+    if (typeof value === "function") {
+      this.createReaction(() => {
+        let newValue = value();
+        setter(newValue);
+      });
+    } else
+      setter(value);
+    getter[GetterMark] = true;
+    setter[SetterMark] = true;
+    return [getter, setter];
+  }
+  triggerReaction(index, measureOfChange, paired) {
+    if (!this.inBatchReactions && !paired)
+      this.ScheduleAutoBatchRuns();
+    this.batchedReactionsToRun[index] = Math.max(
+      measureOfChange,
+      this.batchedReactionsToRun[index] || 0
+    );
+  }
+  enablePairing(sourceReactive) {
+    this.allowedPairedReactives.add(sourceReactive);
+  }
+  createReaction(func) {
+    let reactionIndex = this.reactionIndex++;
+    this.reactions[reactionIndex] = func;
+    this.reactionGlobalKey[reactionIndex] = [this, reactionIndex];
+    this.reactionDependencies[reactionIndex] = /* @__PURE__ */ new Set();
+    this.runReaction(
+      reactionIndex,
+      2
+      /* FULL */
+    );
+  }
+  batchReactions(func) {
+    if (this.inBatchReactions || this.inFlush)
+      return func();
+    this.inBatchReactions = true;
+    [this.dirty, this.dirtyResolve] = mkResolvablePromise();
+    try {
+      return func();
+    } finally {
+      this.flush();
+      this.inBatchReactions = false;
+      this.dirtyResolve();
+    }
+  }
+  ScheduleAutoBatchRuns() {
+    if (!this.isAutoBatchScheduled) {
+      this.isAutoBatchScheduled = true;
+      [this.dirty, this.dirtyResolve] = mkResolvablePromise();
+      this.timeout = setTimeout(() => {
+        this.timeout = void 0;
+        this.flush();
+      }, 0);
+    }
+  }
+  toBeClean() {
+    return this.dirty;
+  }
+  runReaction(reactionIndex, measureOfChange) {
+    this.reactionDependencies[reactionIndex].forEach(
+      (resetDependency) => resetDependency(this.reactionGlobalKey[reactionIndex])
+    );
+    this.reactionDependencies[reactionIndex].clear();
+    pushRunningReaction(this.reactionGlobalKey[reactionIndex]);
+    try {
+      this.reactions[reactionIndex](measureOfChange);
+    } finally {
+      popRunningReaction();
+    }
+  }
+  flush() {
+    if (this.inFlush || this.disabled)
+      return;
+    this.inFlush = true;
+    try {
+      for (let index = 0; index < this.batchedReactionsToRun.length; index++)
+        if (this.batchedReactionsToRun[index])
+          this.runReaction(index, this.batchedReactionsToRun[index]);
+      if (this.isAutoBatchScheduled) {
+        this.isAutoBatchScheduled = false;
+        if (this.timeout)
+          clearTimeout(this.timeout);
+        this.timeout = void 0;
+      }
+      this.batchedReactionsToRun = [];
+      this.dirtyResolve && this.dirtyResolve();
+    } finally {
+      this.inFlush = false;
+      this.reactivesToFlush.forEach((reactive) => {
+        if (!reactive.inBatchReactions)
+          reactive.flush();
+      });
+      this.reactivesToFlush.clear();
+    }
+  }
+  enable() {
+    this.disabled = false;
+    this.flush();
+  }
+  disable() {
+    this.disabled = true;
+  }
+}
+function mkResolvablePromise() {
+  let resolve;
+  let promise = new Promise((res) => resolve = res);
+  return [promise, resolve];
+}
+let _mkReactive = (...reactiveNames) => new Reactive();
+function setMkReactive(mkReactive2) {
+  _mkReactive = mkReactive2;
+}
+function mkReactive(...reactiveNames) {
+  return _mkReactive(...reactiveNames);
+}
+export {
+  GetterMark,
+  MeasureOfChange,
+  Reactive,
+  SetterMark,
+  mkReactive,
+  setMkReactive
+};

package/dist/tracing.js

@@ -0,0 +1,197 @@
+import { Reactive, MeasureOfChange, setMkReactive } from "./index.js";
+class ReactiveTracer {
+  constructor(flushToConsole = false) {
+    this.flushToConsole = flushToConsole;
+    this.log = [];
+    this.getStates = [];
+    this.setStates = [];
+    this.scheduledReactions = [];
+    this.inReaction = -1;
+    this.batches = [];
+    this.reactionLogPosition = [];
+    this.ident = "";
+    this.settingSignalFromBatch = "";
+  }
+  logGetState(name) {
+    if (this.inReaction > -1)
+      this.getStates[this.inReaction].add(name);
+  }
+  logSetState(name) {
+    if (this.inReaction > -1)
+      this.setStates[this.inReaction].add(name);
+    else {
+      this.scheduledReactions[this.inReaction] = /* @__PURE__ */ new Set();
+      this.settingSignalFromBatch = name;
+    }
+  }
+  logAfterSetState() {
+    if (this.inReaction === -1) {
+      const scheduledReactions = [...this.scheduledReactions[this.inReaction]].sort().join(",");
+      this.doLog(
+        `${this.batches.join(", ")} - batch: -> (${this.settingSignalFromBatch}) --> (${scheduledReactions})`
+      );
+    }
+  }
+  beforeReaction() {
+    this.inReaction++;
+    this.getStates[this.inReaction] = /* @__PURE__ */ new Set();
+    this.setStates[this.inReaction] = /* @__PURE__ */ new Set();
+    this.scheduledReactions[this.inReaction] = /* @__PURE__ */ new Set();
+    this.reactionLogPosition.push(this.log.length);
+    this.ident += "  ";
+  }
+  completeReaction(name, reactionName) {
+    this.ident = this.ident.slice(0, -2);
+    const reactionLogPosition = this.reactionLogPosition.pop();
+    const signalGetters = [...this.getStates[this.inReaction]].sort().join(",");
+    const signalSetters = [...this.setStates[this.inReaction]].sort().join(",");
+    const scheduledReactions = [...this.scheduledReactions[this.inReaction]].sort().join(",");
+    const logMessage = `${this.ident}${name} - ${reactionName}: (${signalGetters}) -> (${signalSetters}) --> (${scheduledReactions})`;
+    this.log.splice(reactionLogPosition, 0, logMessage);
+    this.inReaction--;
+    if (this.inReaction === -1)
+      this.flushLog();
+  }
+  beforeBatch(name) {
+    this.batches.push(name);
+  }
+  completeBatch() {
+    this.batches.pop();
+  }
+  flush(name) {
+    this.doLog(`${name} - flush!!!`);
+    this.ident += "  ";
+  }
+  flushEnd(name) {
+    this.ident = this.ident.slice(0, -2);
+    this.doLog(`${name} - flush end`);
+  }
+  logToBeClean(name) {
+    this.doLog(`${name} - await toBeClean!!!`);
+  }
+  triggerReaction(name, index, scheduleAutoBatchRuns) {
+    this.scheduledReactions[this.inReaction].add(
+      `${name} - ${formatReactionName(index)}${scheduleAutoBatchRuns ? " async" : ""}`
+    );
+  }
+  createSignal(name, stateName) {
+    this.doLog(`${name} - createSignal ${stateName}`);
+  }
+  doLog(message) {
+    this.log.push(`${this.ident}${message}`);
+    if (this.inReaction === -1)
+      this.flushLog();
+  }
+  flushLog() {
+    if (this.flushToConsole) {
+      this.log.forEach((entry) => console.debug(entry));
+      this.log = [];
+    }
+  }
+}
+const romanNumerals = {
+  M: 1e3,
+  CM: 900,
+  D: 500,
+  CD: 400,
+  C: 100,
+  XC: 90,
+  L: 50,
+  XL: 40,
+  X: 10,
+  IX: 9,
+  V: 5,
+  IV: 4,
+  I: 1
+};
+function toRoman(num) {
+  let roman = "";
+  for (let i in romanNumerals) {
+    while (num >= romanNumerals[i]) {
+      roman += i;
+      num -= romanNumerals[i];
+    }
+  }
+  return roman;
+}
+function formatReactionName(num) {
+  return toRoman(num + 1);
+}
+class ReactiveWithTracking extends Reactive {
+  constructor(name, reactiveTracer) {
+    super();
+    this.name = name;
+    this.reactiveTracer = reactiveTracer;
+    this.stateIndex = 1;
+  }
+  createSignal(value, measureOfChange = MeasureOfChange.FULL) {
+    const stateName = this.name + this.stateIndex++;
+    this.reactiveTracer.createSignal(this.name, stateName);
+    const [getter, setter] = super.createSignal(value, measureOfChange);
+    const loggedSetter = (value2) => {
+      this.reactiveTracer.logSetState(stateName);
+      const ret = setter(value2);
+      this.reactiveTracer.logAfterSetState();
+      return ret;
+    };
+    const loggedGetter = () => {
+      this.reactiveTracer.logGetState(stateName);
+      return getter();
+    };
+    return [loggedGetter, loggedSetter];
+  }
+  createReaction(func) {
+    const reactionName = formatReactionName(this.reactionIndex);
+    super.createReaction((measureOfChange) => {
+      this.reactiveTracer.beforeReaction();
+      try {
+        func(measureOfChange);
+      } finally {
+        this.reactiveTracer.completeReaction(this.name, reactionName);
+      }
+    });
+  }
+  triggerReaction(index, measureOfChange, paired) {
+    this.reactiveTracer.triggerReaction(this.name, index, !this.inBatchReactions && !paired);
+    super.triggerReaction(index, measureOfChange, paired);
+  }
+  batchReactions(func) {
+    this.reactiveTracer.beforeBatch(this.name);
+    try {
+      return super.batchReactions(func);
+    } finally {
+      this.reactiveTracer.completeBatch();
+    }
+  }
+  flush() {
+    this.reactiveTracer.flush(this.name);
+    super.flush();
+    this.reactiveTracer.flushEnd(this.name);
+  }
+  toBeClean() {
+    this.reactiveTracer.logToBeClean(this.name);
+    return super.toBeClean();
+  }
+}
+const globalReactiveTracer = new ReactiveTracer(true);
+let runningNumber = 1;
+function numberToAlphaNumeric(num) {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+  let result = "";
+  while (num > 0) {
+    num--;
+    result = alphabet[num % 26] + result;
+    num = Math.floor(num / 26);
+  }
+  return result || "A";
+}
+setMkReactive((...reactiveNames) => {
+  return new ReactiveWithTracking(
+    [numberToAlphaNumeric(runningNumber++), ...reactiveNames].join("-"),
+    globalReactiveTracer
+  );
+});
+export {
+  ReactiveTracer,
+  ReactiveWithTracking
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@jay-framework/reactive",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./tracing": "./dist/tracing.js"
+  },
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "workspace:^",
+    "@types/node": "^20.11.5",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,284 @@
+# Jay Reactive Module
+
+The Reactive module is a minimal reactive core implementation that handles storing data,
+reacting to data change and detecting if data has actually changed.
+
+Reactive will strive to run reactions as a batch and will do so **sync** when using `batchReactions` or
+**async** if `batchReactions` was not used. When there are pending reactions to be run async, `toBeClean`
+can be used to wait for the reactions to run using `await reactive.toBeClean()`.
+
+The package one class - the `Reactive` which is a simple reactive core, at which reactions are dependent on signals.
+When a signal is updated, any of the dependent reactions are re-run.
+
+The reactions auto track which signals they depend on. On each run of a reaction,
+it will recalculate dependencies to ensure it only depends on signal values that are actually in use.
+A direct impact is that conditions based on signals are supported in reactions, and the reaction rerun will take
+into account the conditions.
+
+Reactive can also pair, creating dependencies between multiple Reactive instances. See the section below on Reactive Pairing
+
+## Notes:
+
+- `Reactive` is intended to be an internal core implementation for state management and not a user facing API.
+- `Reactive` is used by `@jay-framework/component` as state management for components, at which each component has it's own independent
+  instance of `Reactive`.
+- `@jay-framework/component` also defines reactive context which is also using an independent `Reactive` instance.
+- one `Reactive` can depend on a signal from another `Reactive` creating `Reactive` pairing discussed below.
+- `@jay-framework/reactive` is inspired by [solid.js](https://www.solidjs.com/) state management (amazing framework, BTW).
+- `Reactive.enable` and `Reactive.disable` are used by `@jay-framework/component` to disable and enable reactive as a component unmounts and mounts.
+
+## createSignal
+
+```typescript
+type Next<T> = (t: T) => T;
+type Setter<T> = (t: T | Next<T>) => T;
+type Getter<T> = () => T;
+type ValueOrGetter<T> = T | Getter<T>;
+declare function createSignal<T>(
+  value: ValueOrGetter<T>,
+  measureOfChange: MeasureOfChange = MeasureOfChange.FULL,
+): [get: Getter<T>, set: Setter<T>];
+```
+
+Creates a signal getter / setter pair such that when setting signal value, any dependent reaction is rerun.
+The reactions run on `setTimeout(...,0)`, or at the end of a batch when using `batchReactions`.
+
+The getter always returns the signal value
+The setter accepts a new value or a function to compute the next value, as well as a `MeasureOfChange`.
+
+```typescript
+const [getter, setter] = reactive.createSignal(12);
+
+getter(); // returns 12
+setter(13);
+setter((x) => x + 1);
+
+const [getter2, setter2] = reactive.createSignal(() => `signal value is ${getter()}`);
+```
+
+### createSignal parameters
+
+- `value: ValueOrGetter<T>` - an initial value for the signal, or a getter function to track using `createReaction`.
+- `measureOfChange: MeasureOfChange = MeasureOfChange.FULL` - an indicator of how large a change is signal is considered
+  within reactions that depend on this signal (when a reaction is run, it also gets the `max(...measureOfChange)`
+  of all signals that have changed and it depends on).
+
+### getter
+
+the first function returned by `createSignal` is the `getter` function which returns the current value of the signal.
+
+### setter
+
+The second function returned is `setter` which accepts one parameter - a new value for the signal,
+or a function to update the signal value. Note that a change is defined by strict equality - using the `===` and `!==` operators.
+
+## createReaction
+
+```typescript
+export type Reaction = (measureOfChange: MeasureOfChange) => void;
+reactive.createReaction(func: Reaction);
+```
+
+Creates a reaction that re-runs when signals it depends on changes.
+It will re-run on `setTimeout(..., 0)`, or at the end of a batch when using `batchReactions`.
+The `Reaction` accepts a `MeasureOfChange` computed as the `max(...measureOfChange)`
+of all signals that have changed and the reaction depends on.
+
+The `Reaction` function is running once as part of the call to `createReaction` used to figure out what
+initial dependencies to track. On each run of the `Reaction` function dependencies are recomputed and the
+function will only rerun with relevant dependencies are updated.
+
+```typescript
+reactive.createReaction(() => {
+  console.log(signalGetter());
+});
+```
+
+Note that only dependencies (signal getters) that are actually in use are set as dependencies.
+In the following case, the reaction will track signals `a` and `b`, but will not track signal `c` (by design).
+
+```typescript
+const [a, setA] = reactive.createSignal(true);
+const [b, setB] = reactive.createSignal('abc');
+const [c, setC] = reactive.createSignal('def');
+
+reactive.createReaction(() => {
+  if (a()) b();
+  else c();
+});
+```
+
+Once `a` or `b` update, the reaction will rerun.
+
+If `a` is set to false, the reaction will now depend on `a` and `c`.
+
+## batchReactions
+
+```typescript
+reactive.batchReactions(func: () => void);
+```
+
+Batch reaction enables to update multiple signals while computing reactions only once. It is important for
+performance optimizations, to enable rendering DOM updates once when a component updates multiple signals. It
+is built for the component API to optimize rendering.
+
+```typescript
+let reactive = new Reactive((reactive) => {
+  const [a, setA] = reactive.createSignal(false);
+  const [b, setB] = reactive.createSignal('abc');
+  const [c, setC] = reactive.createSignal('def');
+  reactive.createReaction(() => {
+    console.log(a(), b(), c());
+  });
+});
+// will print the console log false abc def
+
+reactive.batchReactions(() => {
+  setA(true);
+  setB('abcde');
+  setC('fghij');
+});
+// will print the console log true abcde fghij
+```
+
+## toBeClean
+
+```typescript
+reactive.toBeClean(): Promise<void>;
+```
+
+returns a promise that is resolved when pending reactions have run. If there are no pending reactions, the promise
+will resolve immediately.
+
+```typescript
+setA(12);
+setB('Joe');
+// waits for reaction to run
+await reactive.toBeClean();
+```
+
+## flush
+
+```typescript
+reactive.flush(): void;
+```
+
+In the case of not using batch reactions, reactive will auto batch the reactions and run them async.
+`flush` can be used to force the reactions to run sync.
+
+```typescript
+setA(12);
+setB('Joe');
+// forces reactions to run synchronosly
+reactive.flush();
+```
+
+## enable & disable
+
+```typescript
+reactive.enable();
+reactive.disable();
+```
+
+Enables and disables the reactive.
+A Disabled reactive will not run reactions.
+
+- When calling enable, the reactive will also flush any pending reactions.
+- Reactive are created, by default, enabled.
+
+## MeasureOfChange
+
+Measure of Change is an optional value passed when creating signals, which is then used to tune how reactions run.
+The `MeasureOfChange` is defined as an ordered enum, at which case the reaction always gets the max `MeasureOfChange`
+from signals that are updated.
+
+It is defined as
+
+```typescript
+export enum MeasureOfChange {
+  NO_CHANGE,
+  PARTIAL,
+  FULL,
+}
+```
+
+At which
+
+- `NO_CHANGE` - allows to update a signal without triggering reactions
+- `PARTIAL` - triggers reactions with the `PARTIAL` measure of change, unless other signals are updated with a higher measure of change
+- `FULL` - triggers reactions with the `FULL` measure of change
+
+see the `@jay-framework/component` library, the `createDerivedArray` function for an example use case.
+
+## enablePairing
+
+Reactive Pairing is useful when an application has multiple reactive instances who need to sync flush between them.
+For instance, with Jay, a context is one reactive and component is another instance of a reactive.
+
+Pairing is created explicitly using the `enablePairing` API,
+then by reading a signal value of reactive `A` from a reaction of reactive `B`.
+When paired, once reactive `A` flushes, it will also trigger a flush of reactive `B` after `A` flush completes,
+which will re-run the reaction in `B` that have read a signal value of `A`.
+
+```typescript
+reactive.enablePairing(anotherReactive);
+```
+
+- `reactive` the reactive from which `anotherReactive` signal values are read. In Jay, a component. The `B` above.
+- `anotherReactive` the reactive from which signal values are read. In Jay, a context. The `A` above.
+
+example:
+
+```typescript
+B.enablePairing(A);
+```
+
+# Reactive Tracing
+
+The reactive library includes the facility to trace how Reactive signals and reactions are running.
+
+To enable reactive tracing, import the `@jay-framework/reactive/tracing` module before starting jay.
+
+```typescript
+import '@jay-framework/reactive/tracing';
+```
+
+Reactive tracing outputs tracing similar to the following:
+
+```
+// on counter example creation
+A - createSignal A1
+A - createSignal A2
+A - createSignal A3
+A - I: (A3) -> () --> ()
+A - II: () -> () --> ()
+A - flush!!!
+A - flush end
+A - batch: -> (A1) --> ()
+A - flush!!!
+A - flush end
+A - batch: -> (A3) --> (A - I)
+A - flush!!!
+  A - I: (A3) -> () --> ()
+A - flush end
+
+// on counter click on a button
+A - flush!!!
+A - flush end
+A - batch: -> (A3) --> (A - I)
+A - flush!!!
+  A - I: (A3) -> () --> ()
+A - flush end
+```
+
+The trace should be read as:
+
+- `A` - each Reactive gets a letter as a name, like `A`, `B`, `C`, etc.
+- `A - createSignal A1` - creating the first signal.
+  - Signals are named after the reactive name + a serial number, like `A1`, `A2`, `A3`, `B1`, etc.
+- `A - I: (A3) -> () --> ()` - running a reaction, including on reaction creation.
+  - Reactions are named after the reaction name + serial roman number, like `A - I`, `A - II`, `A - III`, etc.
+  - The first `()` are the signals read (using getters) in the reaction.
+  - The second `()` are signals written (using setters) in the reaction.
+  - The third `()` are reactions to run once this reaction is running.
+- `A - batch: -> (A3) --> (A - I)` - a batch reaction setting the `A3` signal and scheduling the `A - I` reaction to run.