doc: add CompareOptions.filterer

[JakobJingleheimer]

As noted by Justin in the May plenary, this could have quite some advantages (performance, such as avoiding the needless expense of constructing an Iterator just to immediately exclude all its items).

[gibson042]

I'm a little torn on this, but leaning towards opposition. The only advantage of passing in a predicate rather than applying it to iterator output is that it allows filtering to affect boolean output. But it comes at the cost of making that mode intertwine implementation code with user code, which almost always incurs a performance penalty. I think it's easy enough to get boolean output like const isDifferent = !!deviations.filter(filterer).next().value, and if that much ceremony is too unergonomic then we can push to fix it with a new iterator helper, e.g. const isDifferent = !deviations.filter(filterer).isEmpty().

[gibson042]

What inputs are expected for a and b? If they're values in the object graph, then how does a filterer differentiate

• extra vs. missing vs. mismatch
• property descriptor
• prototype

or just in general, where in the graph its invocation relates to?

[JakobJingleheimer]

Ah, yes, I suppose the type of A and B are not unknown: they're a primitive (or "special" key). And a couple things are missing.

So I guess the type would be more like:

Suggested change

	filterer?: (a: unknown, b: unknown) => boolean,
	filterer?: (
	a: Primitive,
	b: Primitive,
	path: (string | Symbol)[],
	reason: 'extra' | 'missing' | 'mismatch',
	) => boolean,

For descriptor, I think we already covered this: A and/or B would have that special key in path (which was missing before, so that probably created the confusion).

RE the "special" path segment, what about a well-known symbol, like Symbol(Deviation:Descriptor) & Symbol(Deviation:Prototype) (or Symbol(DescriptorDeviation) & Symbol(PrototypeDeviation))? I think I'd prefer the : delimited version.

---

Thoughts on mismatch → unequal, equality, or maybe even the equality algo used like same-zero? mismatch seems a little "shit happened" to me 😅

[gibson042]

RE the "special" path segment, what about a well-known symbol, like Symbol(Deviation:Descriptor) & Symbol(Deviation:Prototype) (or Symbol(DescriptorDeviation) & Symbol(PrototypeDeviation))? I think I'd prefer the : delimited version.

The special path segment can't be a symbol, because any such symbol could itself be an actual property key—e.g., { foo: { [Symbol(DescriptorDeviation)]: { value: 42 } } } would have an value-mode path like ["foo", Symbol(DescriptorDeviation), "value"] which could not be distinguished from a similar descriptor-mode path for { foo: 42 }.

Thoughts on mismatch → unequal, equality, or maybe even the equality algo used like same-zero? mismatch seems a little "shit happened" to me 😅

Yeah, I don't love "mismatch" either. "unequal" works for me.

[JakobJingleheimer]

Symbols are unique though, so Symbol(foo) ≠ Symbol(foo). If the symbol we use is well-known, it can be checked and there is no collision.

[JakobJingleheimer]

I think it's easy enough to get boolean output

This isn't about getting a boolean; it's purely about performance (and maybe a little bit about DX—but not related to boolean).

The only advantage of passing in a predicate rather than applying it to iterator output is that it allows filtering to affect boolean output. But it comes at the cost of making that mode intertwine implementation code with user code, which almost always incurs a performance penalty.

Before I opened this, I checked with Oli, who said this would likely have relatively significant perf benefits:

• For each filtered deviation, it would save the cost of constructing the more expensive Deviation.
• When all deviations are filtered out, it saves the cost of constructing the Iterable / Iterator.

[gibson042]

The only advantage of passing in a predicate rather than applying it to iterator output is that it allows filtering to affect boolean output. But it comes at the cost of making that mode intertwine implementation code with user code, which almost always incurs a performance penalty.

Before I opened this, I checked with Oli, who said this would likely have relatively significant perf benefits:

• For each filtered deviation, it would save the cost of constructing the more expensive Deviation.

I'm extremely skeptical here. Is he saying that constructing an { actual, expected, path, reason } object is more expensive than calling a user-defined function with (actual, expected, path, reason) arguments??

• When all deviations are filtered out, it saves the cost of constructing the Iterable / Iterator.

Given how commonplace for...of loops are, I also don't buy this as a motivation.

Trying to optimize performance at this stage just seems misguided. From my perspective, the only argument to be made for filterer that makes sense is ergonomics of the boolean-output use case—e.g., const isUnchanged = !compare(old, new, { filterer }); rather than const isUnchanged = !compare(old, new, { mode: "full" })?.filter(filterer).next().value;.