History in incremental computations

[brucou]

I fail to understand the semantics of history length. I believe that may deserve some more explanations in the documentations.

I used the following code (https://codesandbox.io/s/bold-monad-u8dtsf?file=/src/index.js) --- largely inspired from the docs --- to experiment with different values in history lengths. There is no apparent difference in behavior which leaves me perplexed about what role the history parameter plays.

import { Patch, produceWithPatches, enablePatches } from "immer";
import { Atom, atom, computed, isUninitialized } from "signia";
import { Draft } from "immer";
import { RESET_VALUE, withDiff } from "signia";

enablePatches();

class ImmerAtom {
  constructor(name, initialValue) {
    this.atom = atom(name, initialValue, {
      // In order to store diffs, we need to provide the `historyLength` argument
      // to the atom constructor. Otherwise it will not allocate a history buffer.
      historyLength: 10
    });
  }

  update(fn) {
    const [nextValue, patches] = produceWithPatches(this.atom.value, fn);
    this.atom.set(nextValue, patches);
  }
}

let numMapCalls = 0;
function map(source, fn) {
  return computed(
    source.atom.name + ":mapped",
    (prev, lastComputedEpoch) => {
      numMapCalls++;
      // we need to check whether this is the first time we're running
      if (isUninitialized(prev)) {
        // if so, just map over the array and return it
        return source.atom.value.map(fn);
      }

      // this is not the first time we're running, so we need to calculate the diff of the source atom
      const diffs = source.atom.getDiffSince(lastComputedEpoch);
      console.log("diffs", diffs);
      // if there is not enough history to calculate the diff, this will be the RESET_VALUE constant
      if (diffs === RESET_VALUE) {
        // in which case we need to start over
        console.warn("RESET!!");
        return source.atom.value.map(fn);
      }

      // we have diffs and a previous value
      const [next, patches] = produceWithPatches(prev, (draft) => {
        // apply the upstream diffs while generating a new set of downstream diffs
        for (const patch of diffs.flat()) {
          const index = patch.path[0];
          if (typeof index !== "number") {
            // this will be array length changes
            draft[patch.path[0]] = patch.value;
            continue;
          }
          if (patch.op === "add") {
            if (patch.path.length === 0) {
              // this is a new item in the array, we need to splice it in and call the map function on it
              draft.splice(patch.path[0], 0, fn(patch.value));
            } else {
              // one of the existing items in the array has changed deeply
              // let's call the map function on the new value
              draft[index] = fn(source.atom.value[index]);
            }
          } else if (patch.op === "replace") {
            // one of the existing items in the array has been fully replaced
            draft[index] = fn(patch.value);
          } else if (patch.op === "remove") {
            next.splice(index, 1);
          }
        }
      });

      // withDiff is a helper function that returns a special value that tells Signia to use the
      // provided value and diff
      return withDiff(next, patches);
    },
    {
      historyLength: 1
    }
  );
}

const names = new ImmerAtom("names", ["Steve", "Alex", "Lu", "Jamie", "Mitja"]);

let numReverseCalls = 0;
const reversedNames = map(names, (name) => {
  numReverseCalls++;
  return name.split("").reverse().join("");
});

names.update((draft) => {
  draft.push("David");
});

console.log(reversedNames.value);
console.log(numReverseCalls, numMapCalls);

names.update((draft) => {
  draft[0] = "Sunil";
});
names.update((draft) => {
  draft.pop();
});

names.update((draft) => {
  draft[1] = "Brrbb";
});

console.log(reversedNames.value);
console.log(numReverseCalls, numMapCalls);

historyLength: 1

historyLength: 5

So from this, it seems that historyLength is not linked in any ways to the amount of diffs being accumulated?

[ds300]

historyLength applies to the signal that you define it on, and doesn't effect what other signals store. In this case it seems like you want to be setting historyLength on the root atom (inside the ImmerAtom class)

[ds300]

I believe that may deserve some more explanations in the documentations.

Good call, I'll work on this some more.

[brucou]

I think I understand slightly better now.

Scenario:

1. history length for names set to 1. I do 3 updates to names. reversedNames which depends on names will compute its map operation non-incrementally from names. By the way, how is names computed when reservedNames accesses it? Was it a) updated three times with the latest diff stored, b) updated two times with the latest diff stored, c) something else

I understand it is b?

[ds300]

By the way, how is names computed when reservedNames accesses it

It's not. names is updated eagerly, when you call names.update. The diffs are created as a by-product of the update operation.