WB-29: Implement Enricher Pattern

.clj-kondo/rewrite-clj/rewrite-clj/config.edn

@@ -0,0 +1,5 @@
+{:lint-as
+ {rewrite-clj.zip/subedit-> clojure.core/->
+  rewrite-clj.zip/subedit->> clojure.core/->>
+  rewrite-clj.zip/edit-> clojure.core/->
+  rewrite-clj.zip/edit->> clojure.core/->>}}

.github/workflows/format.yml

@@ -13,6 +13,19 @@ jobs:
           ref: ${{ github.head_ref }}
           token: ${{ secrets.WALL_BREW_BOT_PAT }}
 
+      - name: Cache maven dependencies
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-maven
+        with:
+          path: ~/.m2
+          key: ${{ runner.os }}-clj-${{ hashFiles('**/project.clj') }}
+          restore-keys: |
+            ${{ runner.os }}-clj
+
+      - name: Install Clojure dependencies
+        run: lein deps
+
       - name: Install cljstyle
         uses: just-sultanov/setup-cljstyle@v1
         with:
@@ -22,6 +35,10 @@ jobs:
         run: |
           cljstyle fix --report --report-timing --verbose
 
+      - name: Render Changelog
+        run: |
+          lein sealog render
+
       - name: Commit changes
         uses: stefanzweifel/[email protected]
         with:

.sealog/changes/2-0-0.edn

@@ -13,7 +13,7 @@
                              "Display functions for all unit types."]
                 :changed    ["Internal functions that convert between unit systems now use `brewtility.units`"]
                 :deprecated []
-                :removed    ["`brewility.color` has been removed in favor of `brewtility.units.color`"
+                :removed    ["`brewtility.color` has been removed in favor of `brewtility.units.color`"
                              "`brewtility.units/convert-weight` has been removed in favor of `brewtility.units/convert` and `brewtility.units.weight/convert`"
                              "`brewtility.units/convert-volume` has been removed in favor of `brewtility.units/convert` and `brewtility.units.volume/convert`"
                              "`brewtility.units/convert-temperature` has been removed in favor of `brewtility.units/convert` and `brewtility.units.temperature/convert`"]

.sealog/changes/2-1-0.edn

@@ -0,0 +1,16 @@
+{:version      {:major 2
+                :minor 1
+                :patch 0}
+ :version-type :semver3
+ :changes      {:added   ["`brewtility.units.alcohol-content` for converting and displaying alcohol content."
+                          "`brewtility.units.bitterness` for rendering displayable IBU values."
+                          "`brewtility.units.carbonation` for rendering displayable carbonation values."
+                          "`brewtility.units.specific-gravity` now supports measurements in degrees plato."
+                          "`brewtility.predicates.options` for option map keys shared across predicate namespaces."]
+                :changed ["Functions in `brewtility.calculations` will throw targeted exceptions for invalid values instead of relying on the underlying Math implementation to do so."
+                          "Functions in `brewtility.precision` will throw targeted exceptions for invalid values instead of relying on the underlying Math implementation to do so."
+                          "`brewtility.units` now supports a `:precision` option map key for all conversion functions. This key will round the converted value to the specified number of decimal places. Defaults to the precision of the converted value."
+                          "`brewtility.units.color` now supports a reverse-lookup for known RGBa values."
+                          "All functions in `brewtility.predicates` now support an option map as a second argument to make their arities consistent."]
+                :removed ["`^:const` metadata has been removed from conversion maps"]}
+ :timestamp    "2024-03-11T18:47:13.522931300Z"}

CHANGELOG.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## Table of Contents
 
+* [2.1.0 - 2024-03-11](#210---2024-03-11)
 * [2.0.1 - 2024-03-11](#201---2024-03-11)
 * [2.0.0 - 2023-06-11](#200---2023-06-11)
 * [1.5.0 - 2023-02-13](#150---2023-02-13)
@@ -15,6 +16,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 * [1.1.0 - 2020-08-15](#110---2020-08-15)
 * [1.0.0 - 2020-07-19](#100---2020-07-19)
 
+## 2.1.0 - 2024-03-11
+
+* Added
+  * `brewtility.units.alcohol-content` for converting and displaying alcohol content.
+  * `brewtility.units.bitterness` for rendering displayable IBU values.
+  * `brewtility.units.carbonation` for rendering displayable carbonation values.
+  * `brewtility.units.specific-gravity` now supports measurements in degrees plato.
+  * `brewtility.predicates.options` for option map keys shared across predicate namespaces.
+* Changed
+  * Functions in `brewtility.calculations` will throw targeted exceptions for invalid values instead of relying on the underlying Math implementation to do so.
+  * Functions in `brewtility.precision` will throw targeted exceptions for invalid values instead of relying on the underlying Math implementation to do so.
+  * `brewtility.units` now supports a `:precision` option map key for all conversion functions. This key will round the converted value to the specified number of decimal places. Defaults to the precision of the converted value.
+  * `brewtility.units.color` now supports a reverse-lookup for known RGBa values.
+  * All functions in `brewtility.predicates` now support an option map as a second argument to make their arities consistent.
+* Removed
+  * `^:const` metadata has been removed from conversion maps
+
 ## 2.0.1 - 2024-03-11
 
 * Security
@@ -35,7 +53,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 * Changed
   * Internal functions that convert between unit systems now use `brewtility.units`
 * Removed
-  * `brewility.color` has been removed in favor of `brewtility.units.color`
+  * `brewtility.color` has been removed in favor of `brewtility.units.color`
   * `brewtility.units/convert-weight` has been removed in favor of `brewtility.units/convert` and `brewtility.units.weight/convert`
   * `brewtility.units/convert-volume` has been removed in favor of `brewtility.units/convert` and `brewtility.units.volume/convert`
   * `brewtility.units/convert-temperature` has been removed in favor of `brewtility.units/convert` and `brewtility.units.temperature/convert`

Makefile

@@ -14,6 +14,7 @@ version/major:
 	@ lein change version leiningen.release/bump-version release
 	@ lein sealog bump major
 	@ lein pom
+	@ npm version major --no-git-tag-version
 
 version/minor:
 	$(info Updating minor version and adding CHANGELOG entry...)
@@ -22,6 +23,7 @@ version/minor:
 	@ lein change version leiningen.release/bump-version release
 	@ lein sealog bump minor
 	@ lein pom
+	@ npm version minor --no-git-tag-version
 
 version/patch:
 	$(info Updating patch version and adding CHANGELOG entry...)
@@ -30,6 +32,7 @@ version/patch:
 	@ lein change version leiningen.release/bump-version release
 	@ lein sealog bump patch
 	@ lein pom
+	@ npm version patch --no-git-tag-version
 
 changelog/render:
 	$(info Rendering CHANGELOG...)

README.md

@@ -3,6 +3,8 @@
 [![Clojars Project](https://img.shields.io/clojars/v/com.wallbrew/brewtility.svg)](https://clojars.org/com.wallbrew/brewtility)
 ![Clojure and ClojureScript CI](https://github.com/Wall-Brew-Co/brewtility/workflows/Clojure%20and%20ClojureScript%20CI/badge.svg)
 [![cljdoc badge](https://cljdoc.org/badge/com.wallbrew/brewtility)](https://cljdoc.org/d/com.wallbrew/brewtility/CURRENT)
+[![GitHub](https://img.shields.io/github/license/Wall-Brew-Co/brewtility)](https://github.com/Wall-Brew-Co/brewtility/blob/master/LICENSE)
+[![Twitter Follow](https://img.shields.io/twitter/follow/WallBrew?style=social)](https://twitter.com/WallBrew)
 
 A Clojure(Script) utility library for all of your brewing needs.
 
@@ -62,6 +64,10 @@ lein test-build
 
 The tests will also execute on the JVM, to ensure the library is compatible for apps in both deployment environments.
 
+## Contributors
+
+<a href="https://github.com/Wall-Brew-Co/brewtility/graphs/contributors"><img src="https://raw.githubusercontent.com/Wall-Brew-Co/brewtility/master/CONTRIBUTORS.svg" alt="The GitHub profile pictures of all current contributors. Clicking this image will lead you to the GitHub contribution graph." /></a>
+
 ## License
 
 Copyright © 2020-2023 - [Wall Brew Co](https://wallbrew.com/)

doc/api/units.md

@@ -30,6 +30,10 @@ This provides a consistent interface to every system of measure, unit type, and
 (units/convert units/volume 20 :teaspoon :liter)
 ;; => 0.099
 
+;; You can also round the conversion to a specified precision
+(units/convert units/volume 20 :teaspoon :liter {:precision 1})
+;; => 0.1
+
 ;; If you only plan on dealing with volumes,
 ;;   then you can import the `brewtility.units.volume` namespace
 (volume/convert 9.99209 :imperial-pint :american-pint)
@@ -72,6 +76,8 @@ Brewtility supports four systems of measure:
 These are the most commonly seen systems in brewing.
 There are measurement functions for the most common types of measurements within these systems:
 
+- [Bitterness](##bitterness)
+- [Carbonation](##carbonation)
 - [Color](##color)
 - [Pressure](##pressure)
 - [Specific Gravity](##specific-gravity)
@@ -80,6 +86,22 @@ There are measurement functions for the most common types of measurements within
 - [Volume](##volume)
 - [Weight](##weight)
 
+### Bitterness
+
+Currently, brewtility supports the following bitterness measurements:
+
+- [IBU](https://en.wikipedia.org/wiki/International_bitterness_units)
+
+While there is currently only one system, the same namespace and functionality exists as the other measurement types.
+This allows for progressive evolution, and provides a consistent interface to every measurement type encoded in the BeerXML specification.
+
+### Carbonation
+
+Currently, brewtility supports the following carbonation measurements:
+
+- [Volumes of CO2](https://en.wikipedia.org/wiki/Carbon_dioxide#Beverages)
+- [Grams per Liter](https://en.wikipedia.org/wiki/Carbon_dioxide#Beverages)
+
 ### Color
 
 Currently, brewtility supports the following types of color:
@@ -89,10 +111,6 @@ Currently, brewtility supports the following types of color:
 - [Lovibond](https://en.wikipedia.org/wiki/Beer_measurement#Colour)
 - [RGBa](https://en.wikipedia.org/wiki/RGBA_color_model)
 
-The `RGBa` system is special, as it can only be used as an argument for the result of a unit conversion.
-Unfortunately, there is not a great deterministic way to cast the values back to the other systems.
-brewtility will thrown an exception in this case and explain the problem.
-
 ### Pressure
 
 Currently, brewtility supports the following types of pressure:
@@ -156,7 +174,7 @@ Currently, brewtility supports the following types of volume:
 - [tablespoon](https://en.wikipedia.org/wiki/Tablespoon)
 - [teaspoon](https://en.wikipedia.org/wiki/Teaspoon))
 
-Given the prevalence of the French spellings in English recipes, both `:litre` and `:liter` can be passed as options.
+Given the prevalence of the non-US spellings in English recipes, both `:litre` and `:liter` can be passed as options.
 
 ### Weight
 

doc/cljdoc.edn

@@ -3,13 +3,14 @@
                    ["Community" {}
                     ["Contributing" {:file "CONTRIBUTING.md"}]
                     ["Code of Conduct" {:file "CODE_OF_CONDUCT.md"}]
+                    ["License" {:file "LICENSE.md"}]
                     ["Security Policy" {:file "SECURITY.md"}]]
                    ["Functionality" {}
                     ["Calculations" {:file "doc/api/calculations.md"}]
-                    ["Color" {:file "doc/api/color.md"}]
                     ["Precision" {:file "doc/api/precision.md"}]
                     ["Predicates" {:file "doc/api/predicates.md"}]
                     ["Units of Measure" {:file "doc/api/units.md"}]
                     ["Wrapping" {:file "doc/api/wrapping.md"}]]
                    ["Adopted Patterns" {}
+                    ["Enricher Pattern" {:file "doc/patterns/enricher-pattern.md"}]
                     ["Symbolic Keywords" {:file "doc/patterns/symbolic_keywords.md"}]]]}

doc/patterns/enricher-pattern.md

@@ -0,0 +1,134 @@
+# Enricher Pattern
+
+In [BeerXML](http://www.beerxml.com/ "The XML standard to encode beer data"), and, by extension, [common-beer-format](https://github.com/Wall-Brew-Co/common-beer-format "A clojure library/spec for BeerXML"), there are specifications which ultimately represent and encode the same concept.
+For a concrete example, consider a sample [equipment](https://github.com/Wall-Brew-Co/common-beer-format/blob/master/src/common_beer_format/equipment.cljc "The specification for a piece of brewing equipment") record.
+
+```clj
+{:name              "8 Gal pot with 5 gal Igloo Cooler"
+ :boil-size         22.71
+ :trub-chiller-loss 0.95
+ :boil-time         60.0
+ :version           1
+ :tun-specific-heat 0.3
+ :batch-size        18.93
+ :display-boil-size "6.0 US Gallons"}
+```
+
+In the above, you can find two representations of the pre-boil volume that piece of equipment held.
+By the standard, the `:boil-size` is standardized to be the volume in litres, and the `:display-boil-size` is meant to represent that value in a region and human friendly way.
+This is great for users; however, it can be unwieldy in applications for a few to store and transmit data which may only be used in the display layer.
+Programmatically, we are often more interested in a smaller subset of the equipment record and will defer computing display values until they are needed.
+
+While the unit conversion is simple, it can often lead to front-end code like this:
+
+```clj
+(defn display-equipment
+  [equipment system-of-measure]
+  [:span
+    [:h1 (:name equipment)]
+    [:ul
+      [:li (str "Boil volume: " (->display (convert-units (:boil-size equipment) system-of-measure)))]
+      (when (:tun-weight equipment)
+        [:li (str "Mash Tun Weight: " (->display (convert-units (:tun-weight equipment) system-of-measure)))])
+      ...
+    ]])
+```
+
+Helper functions may be extracted, but the above code would certainly benefit from the `:display-boil-size` and `:display-tun-weight` fields which may optionally exist on the `equipment` record.
+As a utility library for beer data, brewtility comes with the functionality needed to compute these display fields; however, keeping them as loose datums isn't fully desirable either.
+In the contexts we want display data available for an equipment record, it's much easier to provide that data with the equipment record.
+To that end, this library implements an enrichment pattern.
+
+## Enrichers
+
+An enrichment function is a function from maps to maps, which non-destructively adds to the source value derived information.
+For example, if we know the user's location, we could infer wether Metric or Imperial measurements would be more appropriate to display.
+With that information, we could leverage an enricher to modify the prior equipment example:
+
+```clj
+(def igloo-cooler
+  {:name              "8 Gal pot with 5 gal Igloo Cooler"
+   :boil-size         22.71
+   :trub-chiller-loss 0.95
+   :boil-time         60.0
+   :version           1
+   :tun-specific-heat 0.3
+   :batch-size        18.93})
+
+(require '[brewtility.enrich.equipment :as enrich])
+
+(enrich/enrich-display-boil-size igloo-cooler {:system-of-measure :imperial})
+;; => {:name              "8 Gal pot with 5 gal Igloo Cooler"
+;;     :boil-size         22.71
+;;     :trub-chiller-loss 0.95
+;;     :boil-time         60.0
+;;     :version           1
+;;     :tun-specific-heat 0.3
+;;     :batch-size        18.93
+;;     :display-boil-size "6.0 US Gallons"}
+;;
+```
+
+If we wanted to calculate multiple display values in serial, we can also perform a best-effort enrichment of the entire record.
+
+```clj
+(enrich/enrich-equipment igloo-cooler {:system-of-measure :imperial})
+;; => {:name                      "8 Gal pot with 5 gal Igloo Cooler"
+;;     :boil-size                 22.71
+;;     :trub-chiller-loss         0.95
+;;     :boil-time                 60.0
+;;     :version                   1
+;;     :tun-specific-heat         0.3
+;;     :batch-size                18.93
+;;     :display-boil-size         "6.0 US Gallons"
+;;     :display-trub-chiller-loss "0.251 US Gallons"
+;;     :display-batch-size        "5.0 US Gallons"}
+;;
+```
+
+Or, in our example front-end:
+
+```clj
+(defn fetch-equipment!
+  [equipment-id]
+  (-> (http/get (str some-url "/equipment/" equipment-id))
+    :body
+    json/decode
+    enrich/enrich-equipment {:system-of-measure :imperial})))
+
+(defn display-equipment
+  [equipment]
+  [:span
+    [:h1 (:name equipment)]
+    [:ul
+      [:li (str "Boil volume: " (:display-boil-size equipment))))]
+      (when (:display-tun-weight equipment)
+        [:li (str "Mash Tun Weight: " (display-tun-weight equipment))])
+      ...
+    ]])
+
+(defn fetch-and-display-equipment!
+  [equipment-id]
+  (-> equipment-id fetch-equipment! display-equipment))
+```
+
+In the above, we're able to calculate display values for the boil size, batch size, and trub chiller loss since the data sources for that information.
+While the equipment record does specify display values for the tun's volume, the source of that data is missing- and therefore excluded.
+
+## Implementations
+
+Enricher functions exist for each of the core specifications supported by BeerXML and common-beer-format.
+
+- [Equipment](https://github.com/Wall-Brew-Co/brewtility/blob/master/src/brewtility/enrich/equipment.cljc "Equipment enrichers")
+- [Fermentables](https://github.com/Wall-Brew-Co/brewtility/blob/master/src/brewtility/enrich/fermentables.cljc "Fermentable enrichers")
+- [Hops](https://github.com/Wall-Brew-Co/brewtility/blob/master/src/brewtility/enrich/hops.cljc "Hop enrichers")
+- [Mash](https://github.com/Wall-Brew-Co/brewtility/blob/master/src/brewtility/enrich/mash.cljc "Mash enrichers")
+- [Miscs](https://github.com/Wall-Brew-Co/brewtility/blob/master/src/brewtility/enrich/miscs.cljc "Misc enrichers")
+- [Recipes](https://github.com/Wall-Brew-Co/brewtility/blob/master/src/brewtility/enrich/recipes.cljc "Recipe enrichers")
+- [Styles](https://github.com/Wall-Brew-Co/brewtility/blob/master/src/brewtility/enrich/styles.cljc "Style enrichers")
+- [Waters](https://github.com/Wall-Brew-Co/brewtility/blob/master/src/brewtility/enrich/waters.cljc "Water enrichers")
+- [yeasts](https://github.com/Wall-Brew-Co/brewtility/blob/master/src/brewtility/enrich/yeasts.cljc "Yeast enrichers")
+
+## Inspiration
+
+- [Maybe Not - Rich Hickey](https://www.youtube.com/watch?v=YR5WdGrpoug&ab_channel=ClojureTV "A great presentation on the types of problems type systems try to solve")