Pathom Updates 1 - Docsite and implicit outputs

Today I’ll bring some updates on the development of Pathom.

Pathom 3 Documentation Site

Pathom 3 is getting a new website! This website will contain general information about Pathom and the latest documentation.

Here is a preview of the front-page:

Most of my work time has been writing new docs, on the past weeks I have written on resolvers, built-in resolvers and smart maps. This is the current plan:

• Rationale
• Tutorial
• Using Pathom
  • Resolvers
  • Built-in resolvers
  • Smart Maps
  • EQL
  • Environment
• Modeling Guides
• How Pathom Works
  • Indexes
  • Planner
  • Runner

I intend to release this website at the same time with Pathom 3 first alpha, to avoid the same mistakes I did in the past (missing docs) I’ll make an extra effort to keep docs in sync with the current implementation.

For the site I’m using Docusaurus v2, this gets back to Markdown (instead of AsciiDoc in the Pathom 2), the site runs really fast, and once released, I can provide an internal search using [Algolia Docsearch]

This should get the best of the worlds, shorter pages, and full-text search.

My goal is first to get the current (minimal) features of Pathom 3 fully documented. With this in place, I’ll release the first public alpha and start iterating on it. Feedback is especially welcome during this period when the API isn’t stable.

Pathom 3 Updates

Although I’m spending most of my time on docs, there were a few changes o Pathom since the project announcement post.

Implicit outputs

In the last post, I talked about the new sugar features of defresolver. Last week I changed the feature single attribute resolver.

I replaced that feature with something I call now implicit outputs. The following snippet compares them:

; using the previous single attribute feature:
(defresolver full-name [env {:acme.person/keys [first-name last-name]}]
  :acme.person/full-name (str first-name " " last-name))

; current, using implicit outputs:
(defresolver full-name [env {:acme.person/keys [first-name last-name]}]
  {:acme.person/full-name (str first-name " " last-name)})

If you look carefully, the difference is that now you return a map in the end, and the defresolver macro will use the shape of that map as the output. For this to work the map must be the last expression in the defresolver body.

Renames on built-in resolvers

As I was writing some docs for the built-in resolvers, I decided to make some names more explicit, so these built-in resolver builders got these new names in Pathom 3:

• alias-resolver2 -> equivalence-resolver
• single-attr-resolver2 -> single-attr-with-env-resolver

There are some new built-in resolvers in Pathom 3:

• static-table-resolver
• attribute-map-resolver
• attribute-table-resolver
• edn-file-resolver

You can learn more about them when the documentation site is out.

defresolver ported back to Pathom 2

After some usage of the new defresolver I got to like it a lot, and I think current users from Pathom 2 can benefit from it as well. So I ported the new defresolver sugar features back to Pathom 2; you can use it in the version 2.3.0-alpha13, have fun!

Check the docs on the macro docstring for details on how to use it!

Follow closer

If you like to know in more details about my projects check my open Roam database where you can see development details almost daily.

Support my work

I'm currently an independent developer and I spent quite a lot of my personal time doing open-source work. If my work is valuable for you or your company, please consider supporting my work though Patreon, this way you can help me have more available time to keep doing this work. Thanks!

Current supporters

And here I like to give a thanks to my current supporters: