Smart maps are a custom map type powered by Pathom resolvers.
With smart maps, you can leverage the power of Pathom processing using the accessible standard Clojure map interfaces.
Using smart maps
To create a smart map, we need the indexes with resolvers, here is a basic example:
When you start a smart map, Pathom creates an atom with the initial data, and then when you request some new information, Pathom triggers the resolver engine, merges the result in the same atom and returns the value for that key, effectively caching it.
This way, the subsequent accesses have the same speed as a local entry.
Nested map values are wrapped with a smart map using the same environment configuration. For example:
This only applies to native Clojure/script maps. It doesn't wrap records and other custom map types.
It also applies for maps inside sequences:
Smart maps do the conversion of sequence items to smart maps on the sequence read. This
means that anytime you read a sequence on a smart map, if the sequence is a
scan will be done eagerly. Otherwise, it will use
map, and the processing is lazy.
By default, if some error happens during the Pathom process, the Smart Map is going
to be silent about it. You can allow the errors to flow up by using the
The options for error mode are:
nilas the value, don't throw errors.
::psm/error-mode-loud: Throw the errors on read.
Disable nested wrap
You can disable the automatic nest wrap using
(psm/with-wrap-nested? false) in the env.
Then all values will return as-is.
You can manually wrap nested values in the same way the library does by using the same env on the value, for example:
If you know the attributes you will need ahead of time, it's more efficient to load then in a single run than fetching one by one lazily.
You can accomplish this using the fn
You can also use
psm/sm-touch-ast! to provide an AST directly.
Smart Maps keys mode is a configuration to decide how a smart map respond to
To change this, use the helper
(psm/with-keys-mode ...), these are the available options
::psm/keys-mode-cached- the default option,
keyswill return the keys cached in the internal smart map atom.
keyswill return all possible keys that are reachable from the current data and the index.
Be careful with
::psm/keys-mode-reachable combined with enabled "nested wrapping".
Considering that, depending on the index and the current data, a simple
Changes to smart maps
You can use the change operations of maps in the smart map (
When a change operation happens, you get a new smart map. Be aware this new smart map
doesn't have the cached data from resolvers from the previous one. The modification is
done from the
source map, the one used to create the smart map in the first place.
This is important so any data computed by resolvers can react to the changes based on the new data context. The following example illustrates this behavior:
Inside smart maps
You can access the smart map environment using
psm/sm-env. This includes all the data
you sent as
env during the smart map creation, plus the cache atom.
Sometimes the result will be unexpected, to debug the smart map you can use the
function to return the run stats of the process:
Smart Maps caching
Smart maps use a durable form of the cache by default. The smart maps add the caches at initialization, and they are persisted when variations of that Smart Map are created.
This means, for example, when you
assoc on a Smart Map, the new returned Smart Map still shares the same plan and resolver caches.
To demonstrate I'll be showing its usage with Reveal in the following video:
Also in REBL: