Support options.normalizeResult callback in wrap(fn, options) to allow reconciling newly computed results with previous results

[benjamn]

Sometimes a function cached with optimism will be spuriously dirtied (directly or indirectly) in a way that triggers recomputation the next time the function is called. The newly computed result may be logically different from the previous result, of course, but if the two results are equivalent (or share equivalent subparts), the developer may wish to keep using (parts of) the previous result.

To take advantage of this system for reconciling cached results, pass an options.normalizeResult callback in the options for the wrap function:

// Use any deep equality test you like:
import { equal } from "@wry/equality"

const range = wrap((n: number): number[] => {
  return n > 0 ? range(n - 1).concat(n - 1) : [];
}, {
  normalizeResult(newer: number[], older: number[]) {
    return equal(newer, older) ? older : newer;
  },
});

Normally, this function would always return the newer array, but using normalizeResult allows the optimism system to continue using older in cases where equal(newer, older), which helps limit referential diversity of range arrays over time.

Since this normalizeResult system works within optimism, at each level of the dependency graph, it should be able to provide referential stability benefits similar to those promised by cache result canonization (apollographql/apollo-client#7439), without using nearly as much memory.