_withValueIn

Produces the instances of this Model that have the specified value -- Function

In serious Querki spaces, you will sometimes find that you want to do something like this this:

value -> +$v
model._instances -> _filter(property -> _equals($v))

That is, you want to collect all of the instances of the model with the given value.

The problem is, the above code is a bit clunky; worse, it's quite slow. This isn't a huge problem when you are only doing it occasionally, for models with modest numbers of instances. But if you are doing it a lot, and you have thousands of instances, it can make pages unusably slow.

This comes up particularly often when representing trees of data in Querki -- where you have "child" things pointing to "parent" ones. When you want to draw this, each parent needs to find all of the instances that point to it, recursively, all the way down. With just a few hundred instances, this can destroy a page.

So this convenience function does exactly the same thing, but in a way that is easier to read and write and is, most importantly, a bazillion times faster. (The important bit is that this caches its results. So while it only runs somewhat faster the first time, it can run orders of magnitude faster if you do it repeatedly.)

So when you need to do this sort of thing, reach for this function: your pages will work better, and it's better for Querki overall.

The syntax is:

value -> model._withValueIn(property)

You can pass a collection of values into this; if so, all Things that match any of them will be produced.

You aren't actually limited to a simple property as the parameter -- you can put any QL expression there, and it will be tried with all instances of the model.

The property or expression may be a collection rather than a single value. If so, this will produces all of the instances where any of the received values match any of the results of the expression.

For the moment, this is only really tested with Thing Type properties. It may work with others, but it certainly needs more work. If you have another type that isn't working, which would be really useful for you, please drop us a line!